Webhooks are not the same thing as Dynamic
Delivery. A webhook notifies you that something
happened; dynamic delivery asks your server for the content to deliver, and
its response is sent to the customer. Use dynamic delivery to generate goods,
and webhooks to observe orders.
Events
event
A new order was created.
event
Payment was received or detected and is settling.
event
The order was delivered. Also fires for manual and re-deliveries.
event
The order was cancelled or expired.
event
The order was refunded. Also emitted when an order enters the Disputed state.
Payload
Each delivery is a JSON envelope containing the event name, the order data, amessageId and a timestamp:
Verifying the signature
Every request is signed with an HMAC signature in theX-Signature header. Verify it against your webhook’s signing secret before trusting the payload - an unverified endpoint will accept anything anyone posts to it.
The verification approach is the same as for dynamic delivery: compute an HMAC-SHA256 of the raw request body using your secret, hex-encode it, and compare against the header. Full code samples for Node.js, Python and PHP are in the Dynamic Delivery guide.
Creating a webhook
1
Open Developers → Webhooks
Each webhook is scoped to one or more of your stores. You can have up to
25 webhooks per user.
2
Enter your endpoint URL
The URL must be HTTP or HTTPS. URLs that resolve to private or reserved
addresses are blocked - the log entry reads “Blocked: webhook URL resolved
to a private or reserved address.”
3
Copy the signing secret
The signing secret is shown exactly once, at creation: “Copy your
signing secret below - it won’t be shown again.” There is no way to view it
later.
Delivery logs
Each webhook has its own execution log. You can filter by status (Success 2xx / Failed 4xx-5xx) and date range, and search by log ID, order ID, or a fragment of the URL. Failed deliveries record a readable reason - TLS or certificate failure, DNS failure, connection refused, or timeout. Each entry also records its attempt/retry number, so you can watch a failed delivery being retried. Resend on any log entry re-sends the original payload using the webhook’s current URL and secret.Paused delivery
If your endpoint fails repeatedly, delivery is temporarily paused and entries appear with response code -1:Delivery is temporarily paused because this endpoint has failed repeatedly. Delivery will resume automatically once it starts responding.Fix the endpoint and delivery resumes on its own - there is nothing to re-enable in the dashboard.
Per-order logs
On any order’s detail page, the Webhook Execution Logs card shows the most recent 100 deliveries for that specific order (date, URL, status code, attempt/retry number, response) - useful when debugging one order rather than a whole endpoint.Endpoint best practices
Respond 2xx quickly, then do the work
Respond 2xx quickly, then do the work
Acknowledge the delivery immediately and process asynchronously. Slow
handlers time out and get retried, which looks like duplicate events.
Be idempotent
Be idempotent
Retries, manual Resend, and re-deliveries all mean the same order can
arrive more than once. Key your processing on
messageId or the order ID.Verify before trusting
Verify before trusting
Check the
X-Signature header on every request, and return 401 when it does
not match.Don't treat webhooks as your only source of truth
Don't treat webhooks as your only source of truth
Endpoints go down. Reconcile periodically against the Orders
API rather than assuming every
event arrived.
Discord notifications are configured in Store Settings → Notifications,
not on the Webhooks page.
Next steps
Webhooks API
Create, update and inspect webhooks programmatically.
Webhook Logs API
Read delivery logs and resend deliveries.
Dynamic Delivery
Generate delivery content on demand from your own server.
Managing Orders
What each order event means operationally.