Webhooks send an automatic notification to a URL you choose whenever something happens in your account, such as a booking being created or a payment succeeding. Instead of checking for changes manually, your own systems stay in sync in real time.
Getting started
Navigate to Settings > Company settings from the sidebar, then open the API tab. The Webhooks section lists your endpoints.
How it works
An endpoint is a URL on your server that receives event notifications. Each endpoint has its own list of subscribed events, an active toggle, and a signing secret. Only https URLs that resolve to a public address are accepted.
Every request is signed with the endpoint's secret in the X-OTC-Signature header, so your server can verify the notification really came from Off The Couch. Failed deliveries are retried automatically with increasing delays, and an endpoint that keeps failing is disabled to protect your server and ours.
Each endpoint card shows a status dot (active or disabled), the endpoint URL with a copy icon, the number of subscribed events, and the status and time of the last delivery.
Step-by-step guide
Add an endpoint
- In the Webhooks section, click Add endpoint.
- Enter the Payload URL where notifications should be sent.
- Optionally add a Description, for example "Accounting sync".
- Leave the Active switch on. Events are only delivered to an endpoint while it is active.
- Under Events, check each event that should trigger a request to this endpoint. Events are grouped into Bookings, Transactions, Payments, and Events.
- Click Create endpoint.
- A drawer titled Endpoint created shows the signing secret. Copy it now and store it on your server. For security it is not shown in full again, though it can be rotated later.
Edit an endpoint
- Click Edit on the endpoint card.
- Change the URL, description, active switch, or subscribed events.
- Click Save.
Rotate the signing secret
- Click Edit on the endpoint card.
- In the Signing secret section, click Rotate secret.
- Copy the new secret and update it on your server. Rotating invalidates the old secret immediately.
View deliveries
- Click Deliveries on the endpoint card.
- The Recent deliveries drawer lists each delivery with its status, event type, HTTP response code, date and time, attempt count, and any error message.
- Click Load more to page through older deliveries.
- Click Redeliver on a row to send that event again.
Re-enable a disabled endpoint
- An endpoint disabled after repeated failures shows a Disabled pill on its card.
- Fix the receiving server, then click Re-enable on the card.
Delete an endpoint
- Click the trash icon on the endpoint card.
- Confirm in the dialog. Deliveries stop immediately.
Reference
Event types
Each subscription row in the Events list shows the event type code it sends. The same code can have more than one subscription row when the trigger differs.
| Event type | Sent when |
|---|---|
| booking.created | A booking is created. Separate rows cover bookings made by customers online and bookings created by staff, including bookings staff add to an existing transaction |
| booking.cancelled | A booking is cancelled, on its own or as part of a transaction cancellation |
| booking.reactivated | A cancelled booking is reactivated |
| booking.datetime_updated | A booking's date or time is changed |
| booking.group_size_updated | A booking's group size is changed |
| booking.rescheduled | A booking is moved to a different time slot |
| transaction.created | A new transaction is created |
| transaction.cancelled | A transaction is cancelled |
| payment.succeeded | A payment completes successfully |
| payment.refunded | A payment is refunded |
| event.completed | An event session is completed |
Good to know
- Notifications include a summary of the affected record, such as the booking, its parent transaction totals, and the customer, so most integrations do not need a follow-up lookup.
- booking.created for staff-created bookings is sent whether or not the staff member chose to send a confirmation email. Webhook delivery is independent of email settings.
- Redelivering an event sends the record's current data, not a snapshot from the original send.
- Delivery history is kept for about 90 days. Older deliveries can no longer be redelivered.
- Billing counts events sent, not delivery attempts. Retries are free.
FAQ
Q: My endpoint stopped receiving events. What happened?
A: Check the endpoint card. If it shows a Disabled pill, it was turned off after repeated delivery failures. Fix the receiving server and click Re-enable. Also confirm the Active switch is on under Edit.
Q: I lost my signing secret. Can I see it again?
A: The full secret is only shown once, right after creation or rotation. Click Edit on the endpoint and use Rotate secret to generate a new one, then update your server.
Q: Why was my URL rejected when creating an endpoint?
A: Only https URLs that resolve to a public address are accepted. Local, private, or http-only addresses are rejected.