Webhooks#
Webhooks are HTTPS requests that Yusr sends to your server when something happens: a transfer arrives, an account expires, a settlement is paid out. They are the most reliable way to confirm payments, because they reach your backend even if the customer closes the checkout page.
Every webhook is signed, retried for about 22 hours if your server doesn't answer, and delivered at least once.
Event types#
| Event | Sent when |
|---|---|
transaction.paid | The exact amount arrived before expiry, or a top-up completed an underpaid transaction. |
transaction.underpaid | Less than the requested amount arrived. Sent again for each further partial transfer. |
transaction.overpaid | More than the requested amount arrived. |
transaction.expired | The account expired without receiving any money. |
transaction.late_payment | Money arrived after the transaction expired or was cancelled. |
transaction.reversed | Everything received was returned to the payer. |
transaction.cancelled | You cancelled a pending transaction. |
settlement.completed | A settlement was paid out to your bank account. |
Each endpoint subscribes to a list of event types. If you don't pass events when you create an endpoint, it
receives all of them.
The payload#
Every webhook is a POST with a JSON body. The data object holds the full, current
transaction (or settlement for settlement.completed), so you rarely
need a follow-up API call.
| Field | Description |
|---|---|
id | Unique event ID (evt_…), also sent as X-Yusr-Event-Id. Use it to deduplicate. |
type | The event type, also sent as X-Yusr-Event-Type. |
created_at | When the event happened. |
mode | test or live. |
data | { "transaction": … } for transaction events, { "settlement": … } for settlement.completed. |
The same payload is pushed to realtime subscribers and returned by GET /v1/events/{id}.
Register an endpoint#
Register endpoints in the dashboard under Developers → Webhooks, or with the API. You can have up to 10
endpoints per mode, each with its own events and signing secret. Live endpoints must use https:// and resolve
to a public IP address; test endpoints may use http://.
The secret is returned only in this response (and when you roll it). Store it as an environment variable
such as YUSR_WEBHOOK_SECRET.
Verify signatures#
Anyone can send a POST to your webhook URL, so check every request before acting on it. Yusr signs each
delivery with your endpoint's secret:
To verify a request:
- Read the raw request body as bytes, before any JSON parsing.
- Reject the request if
X-Yusr-Timestampis more than 5 minutes (300 seconds) away from your clock. This stops an attacker from replaying an old, validly signed request. - Compute the HMAC-SHA256 of
timestamp + "." + raw bodywith your signing secret, as lowercase hex. - Compare it, in constant time, with each
v1=value inX-Yusr-Signature(the header may hold several, separated by commas). Accept the request if any of them matches. - Respond
400if verification fails.
With the official libraries#
The Node.js and PHP libraries implement all of the above. Python has no official library: use the function in the Python tab, which is tested against our shared test vectors.
Without a library#
If you can't add a dependency, these functions implement the same checks with only the standard library. They mirror the official libraries and pass the same test vectors.
Test vector#
Use this vector in a unit test of your verifier. Pass 1791295200 as the current time (the now argument), or
turn the timestamp tolerance off, because the timestamp is in the past.
| Input | Value |
|---|---|
| Secret | whsec_test_4eC39HqLyjWDarjtT1zdp7dc |
X-Yusr-Timestamp | 1791295200 |
| Raw body | {"id":"evt_01JA9QC0000000000000000000","type":"transaction.paid"} |
X-Yusr-Signature | v1=9003c2c97f1b7c57a1257471cb2567d2a769bb0e2edce25a6f92535d903c3dce |
Your verifier must accept this input, and reject it when the body changes by a single byte, when the secret is different, or when the current time is more than 300 seconds after the timestamp.
Respond quickly#
Yusr counts a delivery as successful when your endpoint returns any 2xx status within 10 seconds.
Anything else (a 3xx redirect, which is not followed, a 4xx or 5xx status, a timeout or a connection error)
is a failure and will be retried.
Acknowledge first, work later: verify the signature, store the event or put it on a queue, return 200, then do
slow work (emails, ERP updates, PDF invoices) in a background job.
Retries#
Failed deliveries are retried with increasing delays. After the first attempt, Yusr tries again:
| Attempt | Delay after previous attempt | Time since first attempt |
|---|---|---|
| 1 | — | 0 |
| 2 | 1 minute | 1 min |
| 3 | 5 minutes | 6 min |
| 4 | 15 minutes | 21 min |
| 5 | 30 minutes | 51 min |
| 6 | 1 hour | 1 h 51 min |
| 7 | 2 hours | 3 h 51 min |
| 8 | 4 hours | 7 h 51 min |
| 9 | 6 hours | 13 h 51 min |
| 10 | 8 hours | 21 h 51 min |
After the tenth attempt (about 22 hours) the delivery is marked as failed. You can still resend it from the
dashboard or with the API. If an endpoint keeps failing for 3 days, it is disabled automatically: its
enabled becomes false and disabled_reason explains why. Fix the endpoint, then re-enable it.
Every attempt is logged with its status code, latency and the first 2,000 characters of your response body. See Developers → Webhooks in the dashboard.
Handle duplicates and ordering#
Delivery is at least once. A retry after a timeout, a manual resend or a network glitch can deliver the same event twice. Make your handler idempotent:
- Record each processed event
id(or theX-Yusr-Event-Idheader) in a table with a unique constraint, and skip events you have already seen. - Make the business action itself idempotent too, for example "mark order 1042 as paid" rather than "add ₦25,000 to the balance".
Events can also arrive out of order, for example transaction.paid before a delayed transaction.underpaid
retry. Use the status inside the payload, which is always the transaction's state when the event was created,
and compare updated_at with what you have stored. When in doubt, fetch the latest state with
GET /v1/transactions/{id}.
Send a test event#
Send a signed sample event to an endpoint to check your handler end to end. The test event is a
transaction.paid event for a placeholder transaction (txn_test_00000000000000000000, reference
test-webhook, metadata {"test": true}), so make sure your handler doesn't ship a real order for it.
The call waits for the attempt and returns the delivery result:
In the sandbox you can also trigger real events with the simulator.
Test locally#
Yusr's servers deliver webhooks, so a URL like http://localhost:3000/webhooks would point at our own
machines, not yours. To receive events on your laptop:
- Start your app locally, for example on port 3000.
- Run a tunnelling service such as ngrok or cloudflared to get a public HTTPS URL that forwards to that port.
- Register the tunnel URL as a test-mode endpoint and copy its secret.
- Create a sandbox transaction and simulate a payment, or send a test event.
To unit test your handler without any network, sign a payload yourself with the library helpers and post it to your route:
Manage endpoints#
Update, disable, delete and inspect endpoints with the API or the dashboard.
Deleting returns { "id": "whk_…", "object": "webhook_endpoint", "deleted": true }.
Roll the signing secret#
Roll a secret if it may have leaked, or as routine hygiene. The new secret takes effect immediately: every delivery after the roll is signed with the new secret only, and the response is the only time you see it.
Events and resending#
Every webhook corresponds to an event that you can list, fetch and resend. This is useful for reconciliation and for recovering after an outage on your side.
GET /v1/events accepts type, transaction, limit (1–100, default 20) and starting_after. A resend queues a
new delivery to every enabled endpoint subscribed to the event type, or only to one endpoint if you pass
{ "endpoint_id": "whk_…" }, and returns { "object": "resend", "queued": 1 }.
Security checklist#
- Verify the signature and timestamp on every request, using the raw body.
- Serve your endpoint over HTTPS (required in live mode).
- Store signing secrets like passwords: environment variables or a secrets manager, never in code.
- Deduplicate by event
id, and make fulfilment idempotent. - Treat the webhook as a trigger, and the amounts inside it as the source of truth only after verification.
- Return
2xxquickly and do slow work asynchronously.