Testing webhooks
Prove your endpoint verifies a delivery and handles a failure, a repeat and a replay, using only what the contract defines.
Sandbox: test money only. No request moves real money.
A webhook receiver is tested by the cases that go wrong: a delivery whose signature does not match, an event that arrives twice, one that arrives late, and one your endpoint failed to accept. This page walks through each with the sandbox.
You need an endpoint first. Webhooks shows how to create one.
Before you start
- The endpoint
urlmust start withhttps://. A server on your own machine needs a public HTTPS address in front of it. - Subscribe the endpoint to the events you will test:
order.processing,order.succeeded,order.failed,order.under_reviewandfunding.credited. - Keep the
idof the endpoint, and its secret where your receiver reads it. Every request on this page uses the id.
Send a test event
Start here: POST / with a type the endpoint subscribes to. The test event is signed and delivered exactly as a real one, so it proves your verification before any order exists. It says "test": true, its order or funding has the all-zero id, and it creates nothing.
- It arrives and verifies. Your receiver checks the signature, sees
test, answers 2xx and acts on nothing. - It is refused when it should be. Point the receiver at another secret, or change one byte of the body in a proxy: the check fails and your endpoint answers with an error. The delivery list shows the failed attempt.
- Every type. Send one of each type you handle. A test
order.failedandorder.under_reviewlet you prove the cases the contract gives no way to cause.
An endpoint takes 20 test events in any hour. Webhooks has the rest of the rules.
// npm install axiosimport axios from 'axios';try { const { status, data: delivery } = await axios. post( 'https:// sandbox-api. nasfampay. com/ v1/ webhook-endpoints/ whe_ 01K7SAMP000000000000000090/ test', { type: 'order. succeeded' }, { headers: { Authorization: `Bearer ${process. env. NASFAM_ SANDBOX_ KEY}`, }, }, ); console. log( status, delivery);} catch ( error) { if ( !axios. isAxiosError( error) || !error. response) throw error; const problem = error. response. data; throw new Error( `${problem. status} ${problem. code}: ${problem. title} ( request ${problem. request_ id})`);}Cause an event
Two requests raise a real event in the sandbox: a test funding and an order. Make either, then confirm the event exists in the event log. The log is independent of your endpoint, so it tells you whether the event was raised at all. A test event is never in it.
If the event is in the log and your endpoint saw nothing, the problem is the delivery. If it is not in the log, no delivery was ever due.
Webhooks shows the request that lists events.
Read the deliveries
GET / lists every attempt, newest first. Read these fields:
| Field | What it tells you |
|---|---|
event_id | Which event the attempt carried. |
attempt | The number of the attempt, from 1. |
status | pending, succeeded, failed or abandoned. |
response_status | The HTTP status your endpoint answered with, when it answered. |
duration_ms | How long your endpoint took. |
next_attempt_at | When a failed attempt will be tried again. |
// npm install axiosimport axios from 'axios';try { const { status, data: deliveries } = await axios. get( 'https:// sandbox-api. nasfampay. com/ v1/ webhook-endpoints/ whe_ 01K7SAMP000000000000000090/ deliveries', { headers: { Authorization: `Bearer ${process. env. NASFAM_ SANDBOX_ KEY}`, }, }, ); console. log( status, deliveries);} catch ( error) { if ( !axios. isAxiosError( error) || !error. response) throw error; const problem = error. response. data; throw new Error( `${problem. status} ${problem. code}: ${problem. title} ( request ${problem. request_ id})`);}Fail on purpose
Make your endpoint answer with an error and cause an event. In the example the endpoint answered 503: the attempt is failed, and next_attempt_at says when the next one is due.
Now fix the endpoint and wait. The next attempt carries the same event_id, so your handler must treat it as the same event.
- Your endpoint has 15 seconds to answer, and any 2xx counts as delivered. A redirect is a failure: it is never followed.
- A failed attempt is retried after 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 14 h, 20 h and 24 h, honouring a
Retry-Afteryour endpoint sends. After the last, the endpoint is disabled.next_attempt_atandattemptsay where a delivery stands. - An attempt marked
abandonedhas been given up on, going by the name of the status. Replay it when your endpoint is ready.
Replay a delivery
POST / sends the same event again and answers 202 with the new delivery. A replay never creates a financial event, so it is safe to use as often as you need.
Replay one delivery twice. Your handler must do its work once: the event id is the same each time.
// npm install axiosimport axios from 'axios';try { const { status, data: delivery } = await axios. post( 'https:// sandbox-api. nasfampay. com/ v1/ webhook-deliveries/ whd_ 01K7SAMP000000000000000090/ replay', null, { headers: { Authorization: `Bearer ${process. env. NASFAM_ SANDBOX_ KEY}`, }, }, ); console. log( status, delivery);} catch ( error) { if ( !axios. isAxiosError( error) || !error. response) throw error; const problem = error. response. data; throw new Error( `${problem. status} ${problem. code}: ${problem. title} ( request ${problem. request_ id})`);}A disabled endpoint
The API can switch an endpoint off. enabled turns false and disabled_reason says why: repeated_failures when deliveries kept failing, gone_410 when your endpoint answered 410 Gone.
Read the endpoint when deliveries stop. Once it is healthy, set enabled to true again.
// npm install axiosimport axios from 'axios';try { const { status, data: endpoint } = await axios. patch( 'https:// sandbox-api. nasfampay. com/ v1/ webhook-endpoints/ whe_ 01K7SAMP000000000000000090', { enabled: true }, { headers: { Authorization: `Bearer ${process. env. NASFAM_ SANDBOX_ KEY}`, }, }, ); console. log( status, endpoint);} catch ( error) { if ( !axios. isAxiosError( error) || !error. response) throw error; const problem = error. response. data; throw new Error( `${problem. status} ${problem. code}: ${problem. title} ( request ${problem. request_ id})`);}What your tests should prove
- A bad signature is refused. Another secret, a changed body or a timestamp more than 5 minutes off is never acted on.
- A test event is never acted on.
testis true: answer 2xx and stop. - A repeat changes nothing. The same event
idtwice has the effect of one. - Order is by
version. An event with a lowerversionthan one you have handled is ignored. - An unknown
typeis ignored. New event types will be added. - The answer is quick. Your endpoint answers first and works afterwards.
- The order is the truth. Before you release value, read
GET /orders/{id}.
The handler in Webhooks does each of these in a few lines.
What you can rely on
- Every delivery is signed with your endpoint's secret.
- Every attempt is recorded, with your endpoint's answer.
- Every event has an
idthat stays the same across attempts and replays. - Every event is in
GET /eventsfor 30 days, whether or not it was delivered. - Any delivery can be replayed.
Webhooks shows the check a receiver makes, and how a rotated secret changes over.
Related guides
- Webhooks: endpoints, event types, what arrives and how to verify it.
- Sandbox scenarios: the outcomes that raise each event.
- Idempotency and safe retries: why a repeat is expected.
