Set up
Your key registers its own webhook:whsec_.
- One webhook per key. Calling
POST /webhooksagain changes the URL and answers 200 with"secret": null: the secret stays the same. To get a new secret,DELETEthe 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 /webhooksshows it (never the secret), andPOST /webhooks/{id}/testsends a signedpingright 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 JSONPOST with this envelope:
created_atis 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.updatedfires for each unit, carrying the order’sorder_id, itsbatch_idand theunitnumber. - Shipments:
data.shipmenthas the fields of the one-token shape:quote_id,status,shipping_cost,holder,expires_at,paid_at,burnandfulfilment. In a multi-token shipment each event is about one token (itsquote_id);GET /shipments/{quote_id}returns the whole box. On Solanaburnis null in the event: fetch the GET for a fresh transaction. - A burn window lapsing sends no event. Watch
expires_atand 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 sameidand the same body. - We send events every two minutes or so, so an event usually arrives within a few minutes of the change.
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 wholewhsec_... 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.

