failed order sends no event — and delivery is at-least-once and
best-effort. Poll the order for a failure, and reconcile periodically.
Events
The payload is customer-safe. An order event carries the order id and status; a
wallet event carries the amounts in FCFA. A code, cost or supplier is never sent:
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.