Webhooks — Hostwise to your site
When anything your brand sells changes — a booking on another channel, a cancellation, an owner block, a listing edit — Hostwise POSTs a signed event to your endpoint within seconds. Events are notifications, not data: they name what changed; your handler re-fetches it through the API.
Registration
Your brand registers one or more endpoint URLs (with your account manager, or on the Brands page). Each endpoint gets a signing secret. Multiple secrets can be valid at once, so rotation needs no flag day.
The delivery
POST https://your-site.com/api/webhooks/alpy
alpy-id: evt_… // unique per event, STABLE across retries — dedup on this
alpy-timestamp: 1786400000 // unix seconds — reject if outside ±5 minutes
alpy-signature: v1,<base64 hmac> // space-separated list during secret rotation
{ "id": "evt_…", "type": "availability.changed", "version": 1,
"occurred_at": "2026-08-11T21:40:52Z", "brand": "yourbrand",
"sequence": 42,
"data": { "listing_ids": ["…"], "from": "2027-01-10", "to": "2027-01-24", "reason": "reservation" } }
Verifying the signature
The signed content is id + "." + timestamp + "." + rawBody — HMAC-SHA256 with your secret,
base64. Verify against the raw body bytes before parsing JSON, accept if any
offered v1,… value matches, and reject timestamps outside ±5 minutes (replay protection).
// Node.js
const expected = crypto.createHmac('sha256', secret)
.update(`${id}.${timestamp}.${rawBody}`).digest('base64');
const ok = header.split(/\s+/).some(p => {
const [v, sig] = p.split(',');
return v === 'v1' && sig.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
});
Event types
| Type | Meaning | Your handler should |
|---|---|---|
availability.changed | The calendar moved for the listings in listing_ids: availability, nightly price or minimum stay (reason is rates for a price or min-stay change). from/to bound the change; when absent, the whole calendar may have moved. | Re-fetch availability for each listed id — the named range when present, the whole window otherwise. |
reservation.changed | A reservation was created, changed or cancelled. external_id is your own reference where Hostwise knows it (null for bookings that did not originate from your site). | Update local status if you track it, then refresh availability for every id in listing_ids. |
listing.changed | Content changed (title, photos, details). | Re-fetch the listing and upsert. |
listing.removed | Withdrawn from your brand. | Deactivate locally. Do not delete — bookings may reference it. |
ping.test | Connectivity test. | Return 200. |
listing_ids is always an
array even for one listing — a relocation frees one listing and books another, and refreshing only the first
leaves the freed one showing as booked.Delivery semantics
- Ordering is not guaranteed. This is why events carry no values: re-fetching at processing time is immune to reordering.
- Retries: a non-2xx or timeout is retried — quickly at first (about 30 seconds), then with exponential backoff up to hourly. Answer 2xx to acknowledge, 5xx for transient trouble. The event
idis identical across retries: dedup on it, and make handlers idempotent. - Coalescing: bursts are folded — many changes in a few seconds arrive as one event carrying the union of listings and the widest date range. Widening is safe by design; your re-fetch just covers a few extra days.
- Sequence:
sequenceis gap-free per brand. A gap means you missed an event — call the catch-up endpoint below for exactly what you missed. - The poll stays. Webhooks accelerate; your scheduled refresh remains the floor that catches anything dropped.
Catch-up — "what did I miss?"
After any outage — yours, Hostwise's, or the network's — ask for everything past the last sequence you
processed, instead of falling back to a full resync. Authenticated with your brand key
(gateway scope); no signature involved, TLS and the credential authenticate the channel.
GET /api/gateway/:brand/events?since_sequence=90180&limit=500
GET /api/gateway/:brand/events?since=2026-08-06T09:00:00Z
{ "brand": "yourbrand", "latest_sequence": 90184, "count": 4, "has_more": false,
"events": [ …the same envelopes the webhook would have delivered… ] }
- Process each event exactly as a webhook delivery — same handler, same dedup on
id(a caught-up event may also have been delivered). - Page with
has_more: repeat from the last sequence you received until it isfalse. - Retention is 30 days. The stream exists from your brand's first day — even before you register a webhook endpoint — so an integration can start pull-only and add push later.
Feed status — "is this feed alive?"
A silent push feed is indistinguishable from a quiet day. This answers without waiting for something to change:
GET /api/gateway/:brand/events/status
{ "brand": "yourbrand", "sequence": 90184,
"last_event_at": "…", "last_delivered_at": "…", "pending": 0,
"endpoints": [ { "active": true, "last_success_at": "…", "last_failure_at": null,
"consecutive_failures": 0 } ] }
Alert if pending grows or consecutive_failures climbs — that is your receiver
failing, and Hostwise backing off. Compare sequence with the last one you processed to detect a
gap proactively.
Receiver checklist
- Capture the raw request body (before any JSON parsing middleware).
- Reject missing headers (400), stale timestamps (400), bad signatures (401).
- Dedup on
alpy-id; mark processed only after the work succeeded, so a crash mid-handling reprocesses rather than drops. - Handle the types above; 200 anything unknown.
- Return 5xx when your upstream fetch fails — Hostwise retries, and your poll heals the gap meanwhile.