Webhooks reference
Every StayBind webhook endpoint, the shared reliability model (verify, dedupe, always-200, self-heal), and which ones you integrate with.
StayBind both receives webhooks (your OTA posting reservations) and calls webhooks internally (payment captures, messaging). They all follow one reliability contract.
The reliability contract
Every inbound webhook does the same three things, and you can rely on it:
200 fast, even on a downstream error, then heal missed work with a background sweep. Providers retry non-2xx, so always-200 prevents retry storms while idempotency + reconcile guarantee nothing is lost.This is why you can post to StayBind aggressively and never worry about duplicates or lost bookings.
Endpoints
| Method · path | Auth | For you? | Purpose |
|---|---|---|---|
POST /webhooks/channel/:connectionId | per-connection secret (x-signature) | Yes | your OTA posts reservations in. See Receive bookings. |
POST /webhooks/razorpay/:connectionId | gateway signature | Indirect | guest payment capture → confirms a checkout booking and writes the ledger hold |
GET · POST /webhooks/whatsapp | Meta HMAC + verify token | Platform | inbound guest WhatsApp messages → the operator inbox |
POST /webhooks/billing/razorpay | gateway signature | Platform | StayBind's own SaaS subscription lifecycle |
GET /kyc/digilocker/callback | OAuth state | Platform | DigiLocker consent-pull callback for guest verification |
Only the channel webhook is something you call. The Razorpay capture webhook is relevant to understand, it's what flips a createCheckout booking to confirmed after the guest pays, but you don't call it; the payment gateway does.
The channel webhook (what you post)
Full details are in Connect a custom OTA → Receive bookings. In short:
POST https://api.staybind.com/webhooks/channel/{connectionId}
Content-Type: application/json
x-signature: <your connection's webhookSecret>Body is a single raw reservation or an array; response is { ok, ingested, acked, conflicts }, always HTTP 200.
Payment capture → booking confirmation
When you use createCheckout, the booking is held as a non-blocking enquiry and the guest is sent a payment link. The gateway calls POST /webhooks/razorpay/:connectionId on capture, and that is what confirms the booking and commits the calendar. To observe it from your side, poll getBooking for status: "confirmed". Guest money settles to the operator (merchant of record), StayBind never pools it.
Sync availability out
How StayBind pushes availability, rate, and restriction changes to your OTA so it mirrors the ledger, with delta pushes, a nightly full sync, and rate limiting.
Canonical model
The provider-agnostic types every integration translates to and from. These are the atoms that flow in and out of the availability ledger.