Receiving webhooks
Nodal sends an HTTPS POST to your server whenever something happens — a payment completes, a mandate is approved, a payout is sent — so you never have to keep asking.
Set up an endpoint
Build a route on your server
It must be a public
https://URL, such ashttps://shop.example.com/webhooks/nodal. Private addresses,localhostand plainhttpare refused.Add it in the portal
Open Integrations, add a webhook endpoint with your URL and choose the events you want. You can have several endpoints, each with its own events.
Store the signing secret
The endpoint's secret starts with
whsec_and is shown once. Store it in your server's environment, e.g.NODAL_WEBHOOK_SECRET. If it leaks, rotate it in the portal.Send a test
Use Send test on the endpoint. You receive a
webhook.testevent, signed like every real one.
What you receive
Every event has the same envelope; data depends on the event type.
Content-Type: application/json
X-Nodal-Signature: t=1761206652,v1=5b1c0e7f…
X-Nodal-Event-Id: evt_Lw8kQ2xP9mRt3v
X-Nodal-Event-Type: checkout.session.completed
X-Nodal-Delivery-Id: whd_Qa7…
{
"id": "evt_Lw8kQ2xP9mRt3v",
"type": "checkout.session.completed",
"createdAt": "2026-10-23T10:04:12.000Z",
"data": {
"id": "cs_V1StGXR8Z5jdHi6BmyT2kq0A",
"amountSzl": "149.99",
"currency": "SZL",
"reference": "Order 1042",
"merchantReference": "order_1042",
"collectionId": "col_8fK2mQ9xLp",
"metadata": { "customerId": "c_77" },
"completedAt": "2026-10-23T10:04:12.000Z"
}
}Verify the signature
Anyone can send a request to your URL, so check every one came from Nodal before acting on it. The X-Nodal-Signature header has a Unix timestamp t and a signature v1:
- Join the timestamp, a full stop and the raw request body, exactly as received:
{t}.{body}. - Compute the HMAC-SHA256 of that string with your whole secret (including
whsec_) as the key, in lowercase hex. - Compare it with
v1in constant time. - Reject the request if
tis more than 5 minutes from your clock, to stop old requests being replayed.
Use the raw body
Verify the bytes you received, before any JSON parsing. Parsing and re-encoding changes spacing and key order, and the signature will no longer match.
<?php
$secret = getenv("NODAL_WEBHOOK_SECRET");
$body = file_get_contents("php://input");
$header = $_SERVER["HTTP_X_NODAL_SIGNATURE"] ?? "";
$parts = [];
foreach (explode(",", $header) as $pair) {
[$k, $v] = array_pad(explode("=", $pair, 2), 2, "");
$parts[$k] = $v;
}
$t = $parts["t"] ?? "";
$expected = hash_hmac("sha256", $t . "." . $body, $secret);
if (!ctype_digit($t) || abs(time() - (int) $t) > 300
|| !hash_equals($expected, $parts["v1"] ?? "")) {
http_response_code(400);
exit;
}
$event = json_decode($body, true);
if (!alreadyProcessed($event["id"])) {
if ($event["type"] === "checkout.session.completed") {
markOrderPaid($event["data"]["merchantReference"], $event["data"]["collectionId"]);
}
rememberProcessed($event["id"]);
}
http_response_code(200);Responding and retries
- Answer with any
2xxstatus within 10 seconds. Do slow work (emails, stock updates) after responding, or in a queue. - Anything else — a timeout, a non-2xx status, a redirect — counts as failed. Redirects are never followed.
- Nodal retries each event for up to 3 days: after 1 minute, 5 minutes, 15 minutes, 30 minutes, 1 hour, 2, 4, 8, 16 and 16 hours, and finally 24 hours — 12 attempts in all. Once your server is back, queued events arrive on their next retry, oldest first.
- If deliveries to an endpoint are still failing an hour after an event, Nodal emails your account's owners and admins, at most once a day per endpoint. You get another email if an event is given up on.
- After the last attempt the delivery is marked failed. You can see every delivery and its response code in the portal under Integrations and redeliver it once your server is fixed.
Don't rely on webhooks alone
Retries can delay an event by hours, and an outage longer than 3 days loses it until you redeliver. For anything that matters — fulfilling an order, crediting an account — also confirm with the API (for example GET /checkout/sessions/:id) and reconcile against GET /collections.
Duplicates and ordering
- The same event can arrive more than once (a retry after a slow response, or a redelivery). The event
idnever changes, so record the ids you have processed and skip repeats. - Events can arrive out of order. Use the
statusin the payload, or fetch the object, rather than assuming the order. For example, acheckout.session.completedafter anexpiredmeans the customer paid.