Docs

Webhooks

Last updated: 22 Nov 2026

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

TypeSent when
stay.createdA stay is booked
stay.updatedA stay's dates, room, occupancy or guests change, it is reinstated, or its check-in is undone
stay.cancelledA stay is cancelled or deleted
stay.checked_inA guest checks in
stay.checked_outA guest checks out
booking.createdA booking is made
booking.updatedA booking moves to another time, is restored, or its check-in or no-show is cleared
booking.cancelledA booking is cancelled or deleted
booking.checked_inA guest checks in
booking.no_showA guest is marked as a no-show
order.createdAn order is placed
order.updatedAn 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.cancelledAn order is cancelled
pingSomeone 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.updated events, one for each.
  • A stay that is cancelled and then deleted gets stay.cancelled twice, with different event ids.
  • Registered guests aren't part of the Admin API, so a stay.updated for a guest change shows no difference in the stay but its updated_at.
  • Marking a no-show booking as checked in sends booking.updated for the cleared no-show, then booking.checked_in.
  • Moving a class session sends booking.updated for each booking on it.
  • Cancelling an order sends order.cancelled and an order.updated for each stay, booking or ticket it cancels, alongside each stay's stay.cancelled and each booking's booking.cancelled.
  • Editing an order sends one order.updated for 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

FieldDescription
idThe event's id, the same as its id in the events feed. Retries and Send again reuse it
objectAlways event
typeOne of the types above
createdWhen SERVOS recorded the event, in UTC
api_versionThe payload's version. Fields may be added without notice; a breaking change gets a new version, as in Versioning & stability
data.objectThe 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.