Skip to main content
Webhooks push events to a URL you control. Use them instead of polling — polling an orders endpoint is the fastest way to exhaust a key’s rate limit. Set them up in Growth → API, or with a key holding webhooks:manage.

Events

One endpoint can take all of them, or run several.

The request

POST to your URL:
Body
You have 30 seconds to respond. Any 2xx counts as success.

Verify the signature

Always verify. Your webhook URL is reachable by anyone who learns it, and an unverified handler will happily process a forged order.paid.
The signature is t={unix_timestamp},v1={hex_hmac}, where the HMAC is SHA-256 over `${timestamp}.${rawBody}` using your subscription secret (which starts whsec_).
Node.js
Sign against the raw body, byte for byte. If your framework parses JSON before you see it, re-serialising won’t reproduce the same bytes and every signature will fail. Configure a raw-body handler for this route.
Tolerance defaults to 5 minutes.

Delivery log

Every delivery records its status, HTTP code, duration and the first 1000 characters of your response body. That response snippet is the most useful thing you’ll have when debugging a failing endpoint — so put a real error message in your non-2xx responses rather than an empty body.

Rotating the secret

You can regenerate it. Deliveries signed with the old one stop verifying immediately, so deploy the new secret first, or accept a short window of rejected deliveries.

A good handler

1

Verify first

Before parsing, before any side effect.
2

Respond fast

Acknowledge with a 2xx, then do the work asynchronously.
3

Deduplicate on X-Webhook-ID

Treat it as an idempotency key. Assume you’ll see one twice eventually.
4

Don't trust the payload for money decisions

Read back through the Store API before acting on anything financial.