Skip to content

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 url must start with https://. 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_review and funding.credited.
  • Keep the id of 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 /webhook-endpoints/{id}/test 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.failed and order.under_review let 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.

Code for Send a test event
POST /v1/webhook-endpoints/{id}/testSandbox, test key
// 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 /webhook-endpoints/{id}/deliveries lists every attempt, newest first. Read these fields:

FieldWhat it tells you
event_idWhich event the attempt carried.
attemptThe number of the attempt, from 1.
statuspending, succeeded, failed or abandoned.
response_statusThe HTTP status your endpoint answered with, when it answered.
duration_msHow long your endpoint took.
next_attempt_atWhen a failed attempt will be tried again.
Code for Read the deliveries
GET /v1/webhook-endpoints/{id}/deliveriesSandbox, test key
// 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-After your endpoint sends. After the last, the endpoint is disabled. next_attempt_at and attempt say where a delivery stands.
  • An attempt marked abandoned has been given up on, going by the name of the status. Replay it when your endpoint is ready.

Replay a delivery

POST /webhook-deliveries/{id}/replay 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.

Code for Replay a delivery
POST /v1/webhook-deliveries/{id}/replaySandbox, test key
// 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.

Code for A disabled endpoint
PATCH /v1/webhook-endpoints/{id}Sandbox, test key
// 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. test is true: answer 2xx and stop.
  • A repeat changes nothing. The same event id twice has the effect of one.
  • Order is by version. An event with a lower version than one you have handled is ignored.
  • An unknown type is 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 id that stays the same across attempts and replays.
  • Every event is in GET /events for 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.