Skip to main content
Register an endpoint to receive events as they happen instead of polling. SODACARDS POSTs a signed JSON envelope to your URL; you verify the signature and act on it.

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.
Your endpoint must be HTTPS and publicly reachable. We refuse a URL that resolves to a private, loopback or link-local address.

Verifying a delivery

Each request carries a Sodacards-Signature header:
v1 is HMAC-SHA256(secret, "<t>.<raw-request-body>"), hex-encoded, keyed on your whsec_ secret. To verify:
  1. Read t and v1 from the header.
  2. Reject the delivery if t is more than five minutes from now (replay defence).
  3. Recompute the HMAC over the exact raw body bytes and compare it to v1 in constant time.
During a secret rotation the header may carry several comma-separated 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 on Sodacards-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.