Skip to content

Subscribe a webhook

post/api/v1/webhooks

Registers an https endpoint for booking and guest events, owned by the calling key: what an automation tool calls when a user switches a trigger on (REST hooks). The same endpoints, signature (Gaplessly-Signature), retries and address rules as webhooks added in the dashboard; see the webhooks guide for verifying a delivery.

Each event also needs the read scope for its data, because a webhook pushes what a list endpoint would return: booking.created, booking.updated and booking.cancelled need reservations:read (or appointments:read), and guest.created and guest.merged need clients:read. check.updated (a till's check total, table reservations only; an appointments business is a 400) needs reservations:read. message.received (a guest's message, with its text) needs messages:read. enquiry.created and enquiry.updated (a big group's enquiry, table reservations only) need reservations:read. Without it the answer is 403 insufficient_scope naming the missing scope.

Only the key that registered an endpoint can remove it, and revoking the key removes all of its endpoints. At most 3 per key, within the organization's 10. A test key's endpoint hears only its sandbox's bookings. The signing secret is in this response and nowhere else.

Safe to retry. A key subscribing a URL it already subscribed gets that endpoint back with 200, secret included, rather than a second endpoint that would deliver every event twice. A repeat does not change the events; to change them, unsubscribe and subscribe again.

Authorization

bearerApiKey webhooks:write
AuthorizationBearer <token>

Build with a test key (sk_test_...): it works only in your API sandbox and never emails or texts anyone. Scopes, errors and limits.

In: header

Scope: webhooks:write

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/webhooks" \  -H "Content-Type: application/json" \  -d '{    "url": "http://example.com",    "events": [      "booking.created"    ]  }'
{  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "url": "string",    "events": [      "string"    ],    "description": "string",    "createdAt": "2019-08-24T14:15:22Z"  },  "secret": "string"}