Developers

Register an HTTPS endpoint, choose its events, and Supahost POSTs a signed JSON envelope for every matching change.

  • reservation.created: a reservation was created.
  • reservation.updated: a reservation changed, for example new stay dates.
  • reservation.cancelled: a reservation was cancelled.
  • message.received: a guest message arrived from a connected channel.
  • message.sent: a staff reply was queued for delivery to the guest. senderType is staff for a person and for a flow; a flow reply also carries senderFlowId.
  • property.created: a property was created, as a draft.
  • property.updated: property details or active status changed. Deactivation arrives as active: false.
  • property.lifecycle_changed: a property switched on or off, or its connection state changed. cause.kind says whether Supahost did it by itself (automatic, for example after a listing was linked or unlinked in your channel manager) or a team member asked for it (person).
  • task.created: a task was created.
  • task.updated: a task changed, for example a new status.
  • calendar.updated: availability or rates changed for a date range. For a calendar write the range runs from the first to the last night that changed. A calendar write that changes nothing sends none. A rate plan update that changes the base rate sends one with kind rates for the property. A date block created, moved, resized or removed, in the dashboard or with POST, PUT or DELETE on /properties/{propertyId}/blocks, sends one with kind availability_block, from the first to the last blocked night it affects. A change to a block’s reason alone sends none. A price adjustment create, remove or change of anything but its name, in the dashboard or with POST, PATCH or DELETE /price-adjustments, sends one with kind rates for each property it reaches.

One endpoint subscribes to one or more event types. Disabled endpoints receive nothing, and deleting an endpoint also removes its delivery log.

Every delivery is a POST with Content-Type: application/json and the same envelope. The data object identifies what changed; use the public API to read the complete record.

JSON
{
  "id": "41",
  "type": "reservation.created",
  "created": "2026-08-20T10:00:00.000Z",
  "data": {
    "id": "9",
    "propertyId": "1",
    "confirmationCode": "RS-7XK2P9QA",
    "status": "confirmed",
    "arrivalDate": "2030-08-01",
    "departureDate": "2030-08-04"
  }
}
Envelope fields
FieldTypeRequiredDescription
idstringRequiredUnique event ID. Retries and redeliveries of the same event send the same value, so dedupe on it.
typestringRequiredOne of the subscribed event types.
createdstring (date-time)RequiredWhen the event occurred.
dataobjectRequiredThe event payload.
Reservation event data
FieldTypeRequiredDescription
idstringRequiredReservation ID. Read the full record with GET /api/v1/reservations/{id}.
propertyIdstringRequiredProperty ID.
confirmationCodestringRequiredGuest-facing confirmation code.
statusstringRequiredReservation status after the change.
arrivalDatestring (date)RequiredArrival date as YYYY-MM-DD.
departureDatestring (date)RequiredDeparture date as YYYY-MM-DD.
sourcestringOptionalchannex when the change came from a channel webhook; absent for dashboard changes.
channelstring | nullOptionalOriginating channel name (for example booking.com) for channel-sourced events.
externalIdstringOptionalChannel-side booking ID for channel-sourced events.
Property event data
FieldTypeRequiredDescription
idstringRequiredProperty ID. Read the full record with GET /api/v1/properties/{id}.
namestringRequiredProperty name after the change.
timezonestringRequiredIANA time zone.
activebooleanRequiredWhether the property is active after the change.
Property lifecycle event data
FieldTypeRequiredDescription
propertyIdstringRequiredProperty that switched.
workspaceIdstringRequiredWorkspace that owns the property.
fromobjectRequiredState before the change: state (draft, connecting, active, disconnecting, or inactive), active, and requestedActive.
toobjectRequiredState after the change, with the same fields as from.
requestedActivebooleanRequiredWhether the property is meant to be live after the change.
cause.kindstringRequiredautomatic when Supahost made the change by itself, person when a team member asked for it.
cause.reasonstringRequiredFor example active_listing_observed (a listing was linked in your channel manager), no_active_listings_observed (no listing is linked any more), setup_completed, setup_failed, setup_expired, retirement_finished, connection_requested, operator_requested, or relink_completed (a team member reconnected the property to its listings, so cause.kind is person).
cause.channelManagerobject | nullRequiredFor a change after Supahost checked the property's linked listings: ratePlanIds (Supahost rate plan IDs), listings (id, channel), and observedAt. References only. Null otherwise.
occurredAtstring (date-time)RequiredWhen the change was saved.
auditEventIdstring | nullRequiredThe audit record of an automatic change. Null for a person's request, which is audited with the request itself.
Message event data
FieldTypeRequiredDescription
idstringRequiredMessage ID.
threadIdstringRequiredConversation thread ID.
propertyIdstring | nullRequiredProperty the conversation belongs to. Always set on message.received; message.sent can carry null when the thread lookup misses.
reservationIdstring | nullConditionalmessage.received only: linked reservation, when the thread is tied to one.
directionstringRequiredinbound for guest messages, outbound for staff replies.
senderTypestringRequiredguest or staff. A reply sent by a flow is staff and also carries senderFlowId.
senderFlowIdstringConditionalmessage.sent only: the flow that sent the reply. Present only when a flow sent it; absent when a person did. Use it, not senderType, to tell an automated reply from a person.
guestNamestringConditionalmessage.received only: guest display name.
bodystringRequiredMessage text.
occurredAtstring (date-time)RequiredWhen the message was sent, matching the stored record.
Task event data
FieldTypeRequiredDescription
idstringRequiredTask ID.
titlestringRequiredTask title.
categorystringRequiredFor example cleaning, maintenance, or guest.
prioritystringRequiredlow, normal, high, or urgent.
statusstringRequiredTask status after the change: open, in_progress, completed, or cancelled.
propertyIdstring | nullRequiredLinked property, when the task targets one.
reservationIdstring | nullRequiredLinked reservation, when the task targets one.
assigneeUserIdstring | nullRequiredAssigned team member.
dueAtstring (date-time) | nullRequiredDue time, when set.
Calendar event data
FieldTypeRequiredDescription
propertyIdstringRequiredProperty whose calendar changed.
startsOnstring (date) | nullRequiredFirst affected date as YYYY-MM-DD.
endsOnstring (date) | nullRequiredLast affected date as YYYY-MM-DD.
kindstringRequiredWhat changed: availability_block, nightly_availability, or rates.

Supahost signs every delivery with the endpoint signing secret shown once at creation (whsec_…). The Supahost-Signature header contains a timestamp and an HMAC-SHA256 hex digest:

Text
Supahost-Signature: t=1724224800,v1=9f2c…

Compute HMAC_SHA256(secret, "<t>.<raw request body>") and compare it with the v1 value using a constant-time comparison. Reject timestamps older than 5 minutes to stop replayed requests.

Always verify against the raw request body. Parsing and re-serializing JSON can change the bytes and break the signature.

cURL
# Recompute the signature for a received delivery with openssl:
T=1724224800                                   # the t= value from the header
BODY='{"id":"41","type":"reservation.created","created":"2026-08-20T10:00:00.000Z","data":{}}'
printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$SUPAHOST_WEBHOOK_SECRET"
# Compare the hex output with the header's v1= value.
TypeScript
import { createHmac, timingSafeEqual } from 'node:crypto'

export function verifySupahostSignature(
  rawBody: string,
  header: string,
  secret: string,
  toleranceSeconds = 300,
): boolean {
  const parts = Object.fromEntries(
    header.split(',').map((part) => part.split('=')),
  )
  const timestamp = Number(parts.t)
  const age = Math.abs(Math.floor(Date.now() / 1000) - timestamp)
  if (!timestamp || age > toleranceSeconds) return false
  const expected = createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex')
  const received = parts.v1 ?? ''
  return (
    expected.length === received.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(received))
  )
}
Python
import hashlib
import hmac
import time

def verify_supahost_signature(
    raw_body: bytes, header: str, secret: str, tolerance: int = 300
) -> bool:
    parts = dict(part.split("=", 1) for part in header.split(","))
    timestamp = int(parts.get("t", "0"))
    if abs(int(time.time()) - timestamp) > tolerance:
        return False
    signed = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Answer with any 2xx status within 30 seconds to accept a delivery. Supahost tries each delivery up to 10 times over about a day. Every other status, a timeout, and a network error start a retry.

The wait after each failed attempt grows: 30 seconds, 2 minutes, 10 minutes, 30 minutes, 1 hour, 2 hours, 4 hours, 8 hours, and 8 hours. Each wait varies by up to 20% in either direction, so endpoints that fail together do not retry together. The last attempt starts about 24 hours after the first.

  • pending: queued, not yet attempted.
  • delivered: the endpoint answered 2xx.
  • failed: the last attempt failed and a retry is scheduled. nextAttemptAt tells you when.
  • exhausted: the final attempt failed and Supahost stops retrying.

A 410 Gone answer is final: the delivery becomes exhausted at once. A 404 is retried like any other failure, so a deploy that briefly loses a route does not lose events.

With a 429 or 503, you can send a Retry-After header. Supahost waits at least that long before the next attempt, up to 1 hour. A shorter value never makes Supahost retry sooner than its schedule.

The delivery log keeps every attempt: its number, outcome, response status or error, duration, and the time of the next attempt.

Deliveries are at least once. If your endpoint accepts a delivery but the answer is lost, the same envelope is sent again. Retries can also arrive out of order with newer events. Dedupe on the envelope id.

After a delivery is delivered or exhausted, you can send its event again. In Settings → Webhooks, open the endpoint's deliveries and choose Send again. With the API, call POST /api/v1/webhooks/{webhookId}/deliveries/{deliveryId}/redeliver.

Supahost queues a new delivery with the same payload and the same envelope id. It goes to the endpoint's current URL, signed with its current secret, and it gets the full retry schedule. The new delivery shows redeliveryOf with the ID of the first delivery.

Supahost refuses while a delivery of the same event is still pending or failed, and while the endpoint is turned off.

Supahost turns an endpoint off when nothing has been delivered to it for 5 days and at least 10 deliveries in that time used all their attempts. The endpoint then shows status: disabled with disabledReason: delivery_failures and the time in disabledAt. Owners, and members whose role has the Webhooks permission, get a notification in Supahost. No email is sent.

While an endpoint is off, Supahost does not queue deliveries for it. Events that occur while it is off are not sent later, not even after you turn it back on. Deliveries that were already queued wait and continue with their remaining attempts when the endpoint is on again.

Supahost never turns an endpoint back on by itself. Fix the receiver, then turn the endpoint on in Settings → Webhooks or send enabled: true with PUT /api/v1/webhooks/{webhookId}. That clears disabledReason, and the 5 days start again from that time.

Open Settings → Webhooks to add an endpoint, choose its events, and copy its signing secret. Premade setups (Everything, Reservations, Guest messaging, Listings, Operations) subscribe an endpoint to a sensible bundle in one click; individual events can still be toggled underneath. The same card edits, enables, disables, and deletes endpoints and shows each endpoint’s 25 most recent deliveries with status, every attempt, and response code, and sends a finished delivery again. Editing keeps the existing signing secret.

Managing endpoints requires the Webhooks permission, which only the owner role includes by default. Owners can delegate it to trusted team members through a custom role.