webhooks:manage.
Events
One endpoint can take all of them, or run several.
The request
POST to your URL:
Body
2xx counts as success.
Verify the signature
The signature ist={unix_timestamp},v1={hex_hmac}, where the HMAC is SHA-256
over `${timestamp}.${rawBody}` using your subscription secret (which
starts whsec_).
Node.js
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.
