Skip to main content
We tell your server when an order, a sell-back payout or a shipment changes, so you don’t have to poll. Polling still works and is the fallback when your receiver was down for longer than our retries.

Set up

Your key registers its own webhook:
The response is 201 the first time, with the signing secret. The secret is shown once; store it. It starts whsec_.
  • One webhook per key. Calling POST /webhooks again changes the URL and answers 200 with "secret": null: the secret stays the same. To get a new secret, DELETE the webhook and register again.
  • The URL must be a public https:// URL on port 443, with a hostname (not an IP address) and no login in it, up to 2048 characters. The sandbox has the same rule: to receive on your own machine, use a tunnel such as ngrok.
  • GET /webhooks shows it (never the secret), and POST /webhooks/{id}/test sends a signed ping right now and tells you how your receiver answered.
  • Your webhook moves with a key rotation: the new key takes over the same URL and secret. See Authentication and keys.

Events

Every event is a JSON POST with this envelope:
  • created_at is when the change happened.
  • The payload is the current state, not a diff. It is built when we pick the change up (every two minutes), so several quick changes can arrive as one event carrying the latest status, and an intermediate status may never be sent on its own. Act on the status in the payload.
  • Multi-pack orders: nft_order.updated fires for each unit, carrying the order’s order_id, its batch_id and the unit number.
  • Shipments: data.shipment has the fields of the one-token shape: quote_id, status, shipping_cost, holder, expires_at, paid_at, burn and fulfilment. In a multi-token shipment each event is about one token (its quote_id); GET /shipments/{quote_id} returns the whole box. On Solana burn is null in the event: fetch the GET for a fresh transaction.
  • A burn window lapsing sends no event. Watch expires_at and renew.

Delivery and retries

  • A 2xx response is delivered. Anything else is a failure: another status, a redirect (we never follow one), no answer within 5 seconds, or a connection error. Answer fast and do the work afterwards.
  • Retries: after a failure we try again 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours later: 8 attempts in all, over about 45 hours. After the eighth failure the event is dropped; poll to catch up.
  • At least once. The same event can arrive more than once (and events can arrive out of order). Dedupe on id: a retry carries the same id and the same body.
  • We send events every two minutes or so, so an event usually arrives within a few minutes of the change.
Headers on every delivery:

Verify the signature

Check every delivery before trusting it: recompute the HMAC over the raw body (before any JSON parsing), compare in constant time, and refuse a timestamp more than 300 seconds from your clock. Each retry is signed afresh, so a late retry still verifies. The secret is the whole whsec_... string, used as the HMAC key as is.

Polling (the fallback)

Poll, within the request limits, when you have no webhook or missed events: Our background processing runs every two minutes, so most steps finish within a few minutes of the event that triggers them.