Webhooks push events to your server as they happen, instead of you polling the events feed. An organization's owners and admins add an endpoint under Settings → Webhooks, choose the events it receives, and copy its signing secret to your server.
Webhooks use the same objects as the Admin API. With the Thin payload style an event names what changed and you fetch it with an API key; with Snapshot the event carries the object as the Admin API returns it.
The endpoint's URL must be https:// with a valid certificate, reachable from
the internet, and without a username or password in it. SERVOS doesn't send to
private or local addresses.
Events
| Type | Sent when |
|---|---|
stay.created | A stay is booked |
stay.updated | A stay's dates, room, occupancy or guests change, it is reinstated, or its check-in is undone |
stay.cancelled | A stay is cancelled or deleted |
stay.checked_in | A guest checks in |
stay.checked_out | A guest checks out |
booking.created | A booking is made |
booking.updated | A booking moves to another time, is restored, or its check-in or no-show is cleared |
booking.cancelled | A booking is cancelled or deleted |
booking.checked_in | A guest checks in |
booking.no_show | A guest is marked as a no-show |
order.created | An order is placed |
order.updated | An order is edited, its billing details change, a stay on it changes dates, room or occupancy, a stay, booking, ticket or gift card on it is cancelled, a cancellation fee is added, or it's reinstated |
order.cancelled | An order is cancelled |
ping | Someone presses Send test event on the endpoint's page |
An endpoint receives only the types it subscribes to, plus ping on request.
Answer 2xx to types you don't handle, ping included, so SERVOS doesn't
retry them for four days.
An event says what kind of change happened, not which fields changed, and some changes send more than one:
- A change to a stay's dates and room together sends two
stay.updatedevents, one for each. - A stay that is cancelled and then deleted gets
stay.cancelledtwice, with different event ids. - Registered guests aren't part of the Admin API, so a
stay.updatedfor a guest change shows no difference in the stay but itsupdated_at. - Marking a no-show booking as checked in sends
booking.updatedfor the cleared no-show, thenbooking.checked_in. - Moving a class session sends
booking.updatedfor each booking on it. - Cancelling an order sends
order.cancelledand anorder.updatedfor each stay, booking or ticket it cancels, alongside each stay'sstay.cancelledand each booking'sbooking.cancelled. - Editing an order sends one
order.updatedfor the edit and one for each stay it changes and each stay, booking, ticket or gift card it removes.
Some changes send no event. status moves with the calendar without one: a
stay's from Upcoming to Arriving today, Arriving today to No-show, and
In-house to Departing today; a booking's from Upcoming to
Starting soon and In progress, then to Completed if the guest checked in
or No-show if not. An order's fulfillment_status and lifecycle_status
follow its items without an event of their own, and payments and refunds,
which change its payment_status, send no event yet. An order's items show
each stay, booking and ticket as it is now, so a booking's move, check-ins,
no-shows, and a stay's first room or guests change them without an
order.updated; subscribe to the stay.* and booking.* types for those.
A deleted stay or booking keeps its status, in a snapshot and from
GET /admin/v0/stays/{id} or GET /admin/v0/bookings/{id}, so
stay.cancelled or booking.cancelled is what says it ended. A deleted stay
also has deleted_at set.
Request
Each event is a POST with a JSON body:
POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: SERVOS-Webhooks/1.0
webhook-id: 3926fb5c-8df9-4ba2-9410-a929f0bae95b
webhook-timestamp: 1794826800
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=The headers follow Standard Webhooks.
webhook-id is the event's id, and webhook-timestamp is when SERVOS sent
this attempt, in Unix seconds.
Header names can arrive in lower case (over HTTP/2 they always do), so read them without regard to case.
Thin
{
"id": "3926fb5c-8df9-4ba2-9410-a929f0bae95b",
"object": "event",
"type": "stay.updated",
"created": "2026-11-16T11:00:00Z",
"api_version": "2026-11-16",
"data": {
"object": {
"object": "stay",
"id": "585ac396-c6ba-4af9-9742-b9619c39ee99"
}
}
}Fetch the stay with GET /admin/v0/stays/{id}, using a key with stays:read
(Stays), or the booking with
GET /admin/v0/bookings/{id}, using a key with bookings:read
(Bookings), or the order with
GET /admin/v0/orders/{id}, using a key with orders:read
(Orders).
Snapshot
data.object is the data of GET /admin/v0/stays/{id},
GET /admin/v0/bookings/{id} or GET /admin/v0/orders/{id}, plus its
object name. A stay or booking names its customer by customer_id. An
order's customer leaves out name, email, phone, company and tax id, and the
order leaves out billing_address:
{
"id": "3926fb5c-8df9-4ba2-9410-a929f0bae95b",
"object": "event",
"type": "stay.updated",
"created": "2026-11-16T11:00:00Z",
"api_version": "2026-11-16",
"data": {
"object": {
"object": "stay",
"accommodation_id": "1a90f9e8-053b-4c60-b20c-eb70e723f7ac",
"accommodation_name": "Cabin",
"booked_at": "2026-11-02T16:25:18.347+01:00",
"cancelled_at": null,
"check_in_date": "2026-11-16",
"check_out_date": "2026-11-18",
"created_at": "2026-11-02T16:25:18.347+01:00",
"customer_id": "46c53012-a513-4f66-886f-3b33407d91d4",
"deleted_at": null,
"hotel_id": "f3112e0c-ecd9-489e-86db-779099b5283d",
"hotel_name": "Fjord Hotel",
"id": "585ac396-c6ba-4af9-9742-b9619c39ee99",
"nights": 2,
"occupancy_adults": 1,
"occupancy_children": 0,
"occupancy_infants": 0,
"order_id": "02da2419-3a92-451e-87d5-ad2022189241",
"room_id": "1858eff8-ab69-4d75-b9e4-da7b66601a80",
"room_identifier": "Cabin 16",
"status": "Arriving today",
"updated_at": "2026-11-16T12:00:00.000+01:00"
}
}
}Times in the snapshot carry the organization's offset, as the Admin API's do;
the envelope's created is in UTC.
The snapshot is the object as it is when SERVOS first sends the event, not when the change happened. That is usually seconds later, but can be much later, for example when the endpoint was disabled in between, so a snapshot can already include later changes. Retries and Send again resend that same body, and changing an endpoint's payload style changes only events not yet sent.
Since events can arrive out of order, an older snapshot can arrive after a
newer one. A stay's or a booking's updated_at orders them: every change that
sends a stay.* or booking.* event moves it, so of two snapshots of a stay
or a booking, the one with the later updated_at is newer. An order's
updated_at doesn't order them: changes to an order's items leave it as it
was. When your copy must be current, fetch the object.
Ping
A ping names the endpoint, with either payload style:
{
"id": "8d0d6a2e-4f53-4cb5-a1f8-0f7b3d5c9e21",
"object": "event",
"type": "ping",
"created": "2026-11-16T11:00:00Z",
"api_version": "2026-11-16",
"data": {
"object": {
"object": "webhook_endpoint",
"id": "c5b7e0f4-2a19-4d8e-9b6c-71e3f0a4d2b8"
}
}
}Fields
| Field | Description |
|---|---|
id | The event's id, the same as its id in the events feed. Retries and Send again reuse it |
object | Always event |
type | One of the types above |
created | When SERVOS recorded the event, in UTC |
api_version | The payload's version. Fields may be added without notice; a breaking change gets a new version, as in Versioning & stability |
data.object | The object the event is about: its object name (stay, booking, order or webhook_endpoint) and id, or a snapshot |
Verifying the signature
SERVOS signs each event as Standard Webhooks
specifies, so its libraries can check it. Give them the signing secret
(whsec_ included), the request headers, and the raw request body before you
parse it. They reject an event whose signature doesn't match or whose
webhook-timestamp is more than five minutes off the current time:
# gem "standardwebhooks", in a Rails controller
StandardWebhooks::Webhook.new(secret).verify(request.raw_post, request.headers)// npm install standardwebhooks
import { Webhook } from "standardwebhooks"
new Webhook(secret).verify(rawBody, headers)# pip install standardwebhooks
from standardwebhooks.webhooks import Webhook
Webhook(secret).verify(raw_body, headers)To check it without a library: the key is the part of the secret after
whsec_, base64-decoded. webhook-signature holds v1, and the base64
HMAC-SHA256 of "{webhook-id}.{webhook-timestamp}.{raw body}". Compare in
constant time, and reject events whose webhook-timestamp is more than five
minutes off the current time. The header can hold more than one signature,
separated by spaces: accept the event if any v1 signature matches, and
ignore other versions.
Reveal the secret with Reveal next to Signing secret on the endpoint's page. An endpoint's secret can't be changed: if it leaks, add a new endpoint, move your server to its secret, then delete the old one. Events waiting on the old endpoint aren't moved to the new one.
Responding and retries
Answer with any 2xx within 10 seconds, counted from when SERVOS starts
connecting; the body is ignored. Anything else, including a redirect or a
timeout, is a failure, and SERVOS tries again after 1 minute, 5 minutes,
30 minutes, 2 hours, 5 hours, 10 hours, then every 12 hours: 13 attempts over
nearly four days. After the last the delivery is Failed.
Each attempt is signed again with a new timestamp over the same body. Do the
work after answering. Events aren't guaranteed to arrive in order, several can
arrive at once, and the same event can arrive more than once, so de-duplicate
by event id. Record an id once you've processed the event rather than when
it arrives: Send again resends an event with its id, and that is how
someone recovers an event your server accepted but failed to process. With
Thin payloads, fetching the stay gives you its latest state.
Send again is on every delivery that succeeded or failed while the endpoint is enabled, and starts the 13 attempts over.
Changes to an endpoint apply to events already waiting: a new URL receives them, and unsubscribing from a type doesn't stop events of that type already waiting. While an endpoint is disabled, waiting events hold until it's enabled again, and events that happen meanwhile aren't sent to it. Deleting an endpoint drops the events waiting for it.
Catching up
Event deliveries on the endpoint's page shows each delivery's status,
response and attempts. To catch up after downtime longer than the retries
cover, re-sync from the Admin API as described in
Incremental sync. The events feed lists
the same events by the same id, under their internal action names
(stay.room_changed rather than stay.updated), so you can skip the ones you
already processed.