Webhooks
A webhook endpoint is an address Availies sends events to. Delivery happens after a booking is committed, from an outbox of its own, so a slow or broken endpoint never holds up a booking.
Setting one up
- createWebhookEndpoint adds an endpoint. It answers the signing secret once. An account has at most 20 endpoints, switched on or off.
-
Choose the events it receives, by name, or
*for every one, including later ones. The names are on the events page:booking.canceled,booking.created,booking.host_changed,booking.outcome_set,booking.rescheduled,delivery.dead,routing.submitted,webhook.test. -
The address must be
httpson a public host. It is checked as written and through DNS, and again before every attempt. Addresses that resolve to private or loopback ranges, including ones written in mapped forms, are refused. -
testWebhookEndpoint sends a
webhook.testevent once. It names no booking and no person, is not stored and is not retried. - rotateWebhookSecret replaces the secret. By default the old secret keeps working for 24 hours, and deliveries carry both signatures during that time.
Checking the signature
Every delivery is signed as the Standard Webhooks specification describes. Each endpoint has its own secret, shown once.
-
Three headers arrive with the body:
webhook-id,webhook-timestampandwebhook-signature. The signature readsv1,followed by a base64 value. During a rotation the header holds both signatures. -
The signature covers the id, the timestamp and the exact body. The key is the secret after
whsec_, base64 decoded. Check the raw bytes you received, before any JSON parser has touched them. -
The
webhook-idequals theidin the body, and stays the same on every retry and replay of that event. Use it, or the booking version, to ignore a repeat or a stale event.
Bodies
A manage link is a secret. Whoever holds it can move or cancel that booking until the link expires. Treat webhook bodies as credentials: store them encrypted or not at all, and never write them to a log.
Signed samples to test against
These bodies are synthetic. Each was signed with the sample secret by the product's own signer at a fixed time. Verify the body exactly as written, as UTF-8 bytes. The timestamp is old, so set your verifier's freshness window to that time.
webhook.test
The 32 bytes 0, 1, 2 up to 31, written as a Standard Webhooks secret: whsec_ followed by their base64.
content-type: application/json
webhook-id: msg_00000000000000000000000008
webhook-timestamp: 1791363600
webhook-signature: v1,BXKzoPt7ZAcv3qQtYcYjWEk3ibfJtZxhbw+5yCN4wwo=
{"type":"webhook.test","timestamp":"2026-10-07T08:00:00.000Z","id":"msg_00000000000000000000000008","account_id":"acct_00000000000000000000000001","data":{"endpoint_id":"whe_00000000000000000000000002","message":"A test event from Availies. It describes no booking and no person."}}
delivery.dead
The 32 bytes 0, 1, 2 up to 31, written as a Standard Webhooks secret: whsec_ followed by their base64.
content-type: application/json
webhook-id: msg_00000000000000000000000007
webhook-timestamp: 1791363600
webhook-signature: v1,ascplkmMAGR4oycxyhQHpj/S8tWNgO8a7Th679r/pGg=
{"type":"delivery.dead","timestamp":"2026-10-07T08:00:00.000Z","id":"msg_00000000000000000000000007","account_id":"acct_00000000000000000000000001","data":{"delivery_id":"dlv_00000000000000000000000001","endpoint_id":"whe_00000000000000000000000001","event_id":"msg_00000000000000000000000001","event_type":"booking.created","subject_type":"booking","subject_id":"bkg_00000000000000000000000001","attempts":10,"last_http_status":503,"last_error_code":"http_status"}}
How delivery goes
- The first attempt comes right after the booking is committed. Retries follow after about 1 minute, 5 minutes, 30 minutes, 2, 5, 10, 14, 20 and 24 hours, each plus or minus 10 percent. The event is dead after the tenth attempt, about 75 hours in.
-
A
2xxanswer is a delivery. A5xx,408,429,401,403or404answer, a timeout and a network error are retried.Retry-Afteron a429or503only lengthens the wait, by at most 24 hours. -
410is final and switches the endpoint off. Any other4xxand any3xxis final for that event. Redirects are never followed, and the response body is never read. - A call may take 10 seconds, inside a 20-second deadline that also covers the address check.
- An endpoint whose deliveries have only failed for 5 days is switched off. Owners and admins get one email when a run of failures first makes a delivery dead, and one when the endpoint is switched off.
What is promised
| Promise | How |
|---|---|
| Nothing is lost | The event is written in the same database batch as the change it describes. |
| At least once | Delivery is retried with growing delays until the endpoint answers 2xx or the event is dead. |
| Order per booking | Events for one booking arrive in version order. A later one waits until the earlier one is delivered or skipped. A dead earlier one keeps it waiting until it is replayed or skipped. |
| Safe to repeat | The event id and the booking version let a receiver ignore a repeat or a stale event. |
| Visible | Every attempt is recorded. The admin app shows delivery state and can replay. |
Order across different bookings is not promised.
When delivery fails
-
A failed delivery is an event that could not be delivered after all retries. It is announced as
delivery.deadto the account's other endpoints that subscribe to it, never to the one that failed. - listWebhookDeliveries lists an endpoint's deliveries by status, and listWebhookAttempts lists the attempts of one.
- replayWebhookDelivery sends one event again. replayWebhookDeliveries replays an endpoint's failed deliveries in a time range. skipWebhookDelivery gives one up so the events behind it can go.
Reporting back
A receiver can tell Availies what it did with a booking version, through
reportBooking. The latest report per system is kept,
ordered by version and then sequence. An older one changes nothing, the same pair again is a repeat,
and the same pair with other content is refused with conflict. A report is not an event
and not a change to the booking: it sends nothing and writes no version. A webhook endpoint may name
a report_system, the system expected to report back.