Webhooks
Outbound webhooks deliver signed event notifications to your URL whenever something happens on the dealer side: a listing publishes, an order arrives, a customer matches. The signing scheme is deliberately Stripe-shaped, so any verification code you've written for Stripe-style webhooks works here too.
Envelope
Every webhook is a POST to your configured URL with a JSON body shaped like:
- id: unique event ID. Use it to dedupe at-least-once deliveries.
- type: full event name (
listing.published,order.fulfilled, …). - api_version: the version pinned to the integration that produced the event.
- livemode:
falsewhile the integration was in test mode. - data.object: the resource the event is about. See Event catalog.
- data.previous_attributes: present on
*.updated-style events; map of changed fields with their previous values.
Headers
X-WTH-Event-Id identifies the event and never changes, whether we retry it or you replay it. De-dupe on it. X-WTH-Delivery-Id identifies one delivery: it stays the same across the automatic retries of that delivery (only X-WTH-Delivery-Attempt goes up), and a Replay from the dashboard creates a new delivery with a new X-WTH-Delivery-Id and the same X-WTH-Event-Id.
Signing algorithm
The X-WTH-Signature header carries one timestamp and one or more HMAC-SHA256 signatures. The format:
Each v1 value is HMAC_SHA256(signing_secret, "{t}.{rawBody}") as lowercase hexadecimal. The signed string is the timestamp, a literal period, and the raw request body. Exactly the bytes we sent you, no whitespace normalisation.
Multiple v1= values mean we are rotating secrets. Match any of them. Senders never include a stale signature, so seeing more than one v1= is a transient sign of a live rotation, not an error.
Verification recipes
Three implementations of the same algorithm. Pick your language, copy the snippet, deploy. Don't roll your own. The gotchas below bite real integrators.
Gotchas every integrator hits
Read the raw body BEFORE any JSON parser touches it
express.raw()), Laravel, and Symfony auto-parse JSON request bodies into objects. Hashing a re-serialised JSON value gives a different hash because of whitespace / key order / number formatting. Read req.text() / file_get_contents('php://input') first, hash that string, then parse.Constant-time compare, not ===
=== or strcmp: they leak timing. Node: crypto.timingSafeEqual(Buffer.from(a, 'hex'), Buffer.from(b, 'hex')). PHP: hash_equals(\$expected, \$got).Skew check is not optional
|now − t| > 300 seconds.PHP-specific: php-fpm / NGINX request buffering
php://input returns truncated JSON, hash never matches. Set client_max_body_size 10m; and proxy_request_buffering off; on the receiver location. Modern PHP (≥7.0), no need to defensively stripslashes; magic_quotes_gpc is gone.Delivery, retries, dead-letter
We treat any 2xx response as success. Anything else (including non-responses / timeouts) is a failure that triggers a retry on this exact schedule:
| Attempt | Wait before |
|---|---|
| 1 | immediate |
| 2 | 5 seconds |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 5 hours |
| 7 | 10 hours |
| 8 | 10 hours |
After the 8th failed attempt (about 28 hours after the first) a delivery transitions to dead_letter. It stays in the database for forensics but no further automatic retries fire. You can re-fire it manually from the Deliveries tab's Replay button.
Redirects are not followed. A 3xx response counts as a failed attempt and is retried on the schedule above, so configure the final URL your receiver answers on.
A 410 Gone response is special-cased: it is not retried. Five consecutive 410s tell us your endpoint is permanently dead, and we disable the whole integration. That stops webhooks and also API requests, which are refused with 403 integration_disabled until the dealer re-enables the integration in Settings once you've fixed the receiver.
While the integration is paused or disabled, deliveries already in the queue are not sent, except test events you send yourself. They move to dead_letter with the reason "integration disabled", and you can replay them from the Deliveries tab once the integration is enabled again.
Timeouts and idempotency
Each delivery attempt has a 30-second total timeout. Slow receivers will be retried, so design for at-least-once delivery and de-dupe by X-WTH-Event-Id at your end.
A removal can also reach you twice as two different events, each with its own event id: when the first one was queued but the removal was recorded as failed and retried, or, for part.sold_out, when a part's stock is pushed again while it is still zero. Treat listing.sold, listing.unpublished, part.unpublished and part.sold_out as idempotent by the id in data.object.
Reply quickly. If your handler does heavy work (image processing, downstream API calls), enqueue the work and return 200 immediately. A 200 you can't honour is worse than a 5xx that triggers a well-paced retry.
Replay from the dashboard
The Deliveries tab on /channels/custom lists the most-recent 50 deliveries with their status, attempt count, and last response code. Failed and dead-letter deliveries get a Replay button. Clicking it queues the same event as a new delivery (same X-WTH-Event-Id, new X-WTH-Delivery-Id) with a single attempt: a replay that fails is not retried automatically. Useful when you've fixed a bug in your receiver and want to backfill the last few hours.
Echo-suppression
Your own API calls are answered by their responses, not echoed back as events: creating an order and upserting a customer send nothing to your URL, and what an order you reported sold comes back only when the dealer linked it by hand to a line that did not name it by your SKU. Cancelling an order sends no order.cancelled, but the stock it puts back on your channel is announced (listing.in_stock, listing.updated, part.in_stock), because the status a watch goes back to is decided here. Events triggered by other sources (the dashboard, other channel integrations) still fire. Details on the events page.
