Events
The payload is customer-safe: it carries the order id and status, never a code, cost
or supplier. Fetch the codes from the authenticated endpoint once you receive
order.fulfilled.
Registering an endpoint
POST /v1/webhooks with your HTTPS URL and the events you want. The response
returns a signing secret prefixed whsec_, shown once — store it now.
Verifying a delivery
Each request carries aSodacards-Signature header:
v1 is HMAC-SHA256(secret, "<t>.<raw-request-body>"), hex-encoded, keyed on your
whsec_ secret. To verify:
- Read
tandv1from the header. - Reject the delivery if
tis more than five minutes from now (replay defence). - Recompute the HMAC over the exact raw body bytes and compare it to
v1in constant time.
v1= values;
accept the delivery if any one matches.
Verify over the raw body, before any JSON parsing re-serialises it. A
re-encoded body will not match the signature.
Delivery, retries and de-duplication
Delivery is at-least-once, so the same event may arrive more than once: de-duplicate onSodacards-Event-Id. Return any 2xx to acknowledge; a non-2xx, a timeout or a
connection error is retried on a backoff schedule. An endpoint that fails continuously
for several days is automatically disabled, and you are notified.
Respond quickly — acknowledge first, then do your work asynchronously — so a slow
handler does not look like a failed delivery.