Event

Webhook subscriptions let external systems receive platform events as signed HTTP POST requests. Register a URL, choose which event to receive, and the platform delivers a payload each time that event fires for the owning organization.

For the create call see Subscribe to Events via Webhook.

Webhook subscription

A subscription carries:

Field	Purpose
url	Endpoint that receives event deliveries
event_name	The event to subscribe to. Null receives every event the owner can see.
secret	Shared HMAC key. Returned only on creation. Rotate by replacing the subscription.
active	Whether the subscription currently receives deliveries
owner_id	Owning organization

Events

Every delivery uses the same envelope:

{
  "id": "<event id>",
  "event_name": "<event>",
  "timestamp": "<rfc3339>",
  "context": { }
}

The context block carries the entities involved in the event. Optional entities are omitted when not resolvable.

Event	Fires when	Context entities
booking_created	A booking is confirmed and saved	booking, bookable, bookable_type, location, organization, user
booking_updated	A booking is modified	booking, bookable, bookable_type, location, organization, user
booking_canceled	A booking is canceled	booking, bookable, bookable_type, location, organization, user
booking_deleted	A booking is removed	booking, bookable, bookable_type, location, organization, user
booking_ended	A booking's time window has ended	booking, bookable, bookable_type, location, organization, user
checkin_created	A checkin is registered	checkin, booking when linked, bookable, bookable_type, location, organization, user
checkin_started	The user checks in	checkin, booking when linked, bookable, bookable_type, location, organization, user
checkin_updated	A checkin is modified	checkin, booking when linked, bookable, bookable_type, location, organization, user
checkin_failed	A checkin attempt was rejected	checkin, booking when linked, bookable, bookable_type, location, organization, user
checkout_started	The user initiates checkout	checkin, booking when linked, bookable, bookable_type, location, organization, user
checkout_completed	The checkout is finalized	checkin, booking when linked, bookable, bookable_type, location, organization, user
code_scanned	A code is resolved through GET /api/resolve/{code}	code, plus the object the code points at when one is set

Delivery and signing

Each delivery is an HTTP POST with the envelope above as the JSON body. The signature and a timestamp arrive in the X-Samna-Signature header using a timestamped HMAC-SHA256 scheme. Verify the signature against the shared secret with a 5 minute replay window to reject replayed requests.

Failed deliveries are retried with backoff up to three attempts before being dropped.

API

The Event tag covers webhook subscription CRUD.