⬡ Nodal Docs

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

  1. Build a route on your server

    It must be a public https:// URL, such as https://shop.example.com/webhooks/nodal. Private addresses, localhost and plain http are refused.

  2. 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.

  3. 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.

  4. Send a test

    Use Send test on the endpoint. You receive a webhook.test event, signed like every real one.

What you receive

Every event has the same envelope; data depends on the event type.

POST https://shop.example.com/webhooks/nodal
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:

  1. Join the timestamp, a full stop and the raw request body, exactly as received: {t}.{body}.
  2. Compute the HMAC-SHA256 of that string with your whole secret (including whsec_) as the key, in lowercase hex.
  3. Compare it with v1 in constant time.
  4. Reject the request if t is 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.

Verify and handle a webhook
<?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 2xx status 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 id never changes, so record the ids you have processed and skip repeats.
  • Events can arrive out of order. Use the status in the payload, or fetch the object, rather than assuming the order. For example, a checkout.session.completed after an expired means the customer paid.