Written by Ryo — August 11
What a webhook subscription does
A webhook subscription tells Wheelhouse to send data to a URL you control whenever something changes, instead of you having to ask for it.
Once it's set up, Wheelhouse pushes events to your endpoint automatically, so you can keep your own copy of the data fresh without polling.
One subscription covers your entire portfolio — every listing you own, plus any listing shared with you to manage. You don't need to set one up per listing, and you don't need to maintain more than one subscription as your portfolio grows.
Available event types
As of now, you can subscribe to three event types. Events are all tied to a specific listing:
recommendations.updated— a listing's price recommendation changed.reservations.ingested— new reservation data landed for a listing.flags.detected— a listing tripped one of Wheelhouse's flags.
Call GET /webhook_events to get the current list of subscribable event types directly from the API.
How to create a subscription
Decide which event types you want (see above).
Choose an HTTPS endpoint that can receive and respond to
POSTrequests. Wheelhouse only delivers tohttps://URLs.Call
POST /webhooks, passing your endpoint's URL and the event types you want. You can also add a description to label the subscription for your own reference.Save the signing secret from the response immediately — see "Verifying a delivery" below.
Deliveries begin with the next batch window after you create the subscription — you won't receive a backlog of past events.
What's in a delivery
A delivery tells you what changed, not the new values. Instead of including full price, reservation, or flag data, it names the listings affected — in a data.listing_ids array — and expects you to re-read the actual detail through the relevant endpoint (price recommendations, reservations, or flags). This keeps payloads small and stable, and means you never have to reconcile a webhook body against an API response — the API response is always the source of truth.
Deliveries are also batched: events happening within the same 5-minute window collapse into a single request, with every affected listing named in that one delivery's data.listing_ids. So if a nightly repricing run touches your whole portfolio, you get a handful of deliveries — not thousands.
A delivery only ever names listings you have access to.
Handling retries and duplicates
Delivery is at-least-once, which means the same event can arrive more than once — your endpoint needs to handle that.
Retries reuse the same
Wh-Event-Idheader (also present as the envelopeidin the payload). If you've already processed an id, treat the retry as a no-op.Respond with any
2xxstatus as soon as you've durably accepted the delivery — don't wait until you've finished processing it. Wheelhouse times out at 15 seconds, so do your actual work (calling back into the relevant endpoint, updating your systems) after responding, not before.A failed delivery is retried with backoff over roughly 20 minutes.
If a subscription keeps failing, Wheelhouse disables it automatically rather than retrying forever. Re-enable it with
PUT /webhooks/{id}once your endpoint is healthy — this also clears the failure count, so it starts fresh.
Managing a subscription
Use PUT /webhooks/{id} to update a subscription at any time:
Change the URL or description — update just that field; everything else stays as it was.
Change the event types — passing a new list of event types replaces the subscription's full set. Leaving event types out of an update leaves the current set untouched.
Pause deliveries — set the subscription to disabled. No events are sent while it's disabled.
Resume deliveries — re-enable the subscription. This also resets its failure count back to zero.
Delete a subscription — this stops all delivery to it and removes its delivery history permanently.
Debugging deliveries
Call GET /webhooks/{id}/deliveries to see recent delivery attempts, most recent first — including the HTTP status your endpoint returned and the reason for any failure. Delivery history is kept for 7 days.