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

TypeMeaningYour handler should
availability.changedThe 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.changedA 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.changedContent changed (title, photos, details).Re-fetch the listing and upsert.
listing.removedWithdrawn from your brand.Deactivate locally. Do not delete — bookings may reference it.
ping.testConnectivity test.Return 200.
Unknown types must return 200 and be ignored. Hostwise adds event types over time; a receiver that errors on novelty burns its own retry budget. 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

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… ] }

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

  1. Capture the raw request body (before any JSON parsing middleware).
  2. Reject missing headers (400), stale timestamps (400), bad signatures (401).
  3. Dedup on alpy-id; mark processed only after the work succeeded, so a crash mid-handling reprocesses rather than drops.
  4. Handle the types above; 200 anything unknown.
  5. Return 5xx when your upstream fetch fails — Hostwise retries, and your poll heals the gap meanwhile.