Next File Manager 6.1.0: share links, Trash, a phone app and a Health check Next Exams 6.3.0: exam parts, scaled scores, listening and speaking tests Next Restaurant 6.1.0: move your data in, run payroll, and connect other systems Next Inventory 6.2.0: a REST API and webhooks for your other systems Next DB 6.1: Auto-Updating Tables, Printing, Phone Layout and SEO Next Task 6.0.0: a task manager for Joomla
NextSoftware

Verifying signatures

Verifying deliveries are genuine

Every webhook has its own signing secret (6.1). Give it to the receiving system and verify every payload with it before acting on it.

An endpoint URL is not a secret — it can be guessed, logged by a proxy, or leak from a config file. Without signature verification, anyone who learns the URL can post fabricated orders to your integration. With it, a forged request fails the check and is discarded.

Verify the signature before parsing or acting on the body, not after.

What every delivery carries

Header Example Always sent?
webhook-id msg_4e9c1b7a2f08d3516ac4be9017d2f5a3 Yes
webhook-timestamp 1788112371 (Unix seconds) Yes
webhook-signature v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= Only when a secret is set
X-NextRestaurant-Event order.placed Yes
X-NextRestaurant-Signature sha256=6f2b… Only when a secret is set

Two signature schemes go out on every signed delivery, over the same body with the same key. Verify either one — not both.

Standard Webhooks (use this for new integrations)

webhook-signature follows the Standard Webhooks specification, so any library implementing it will verify our deliveries with no custom code.

The signed content is the three parts joined by full stops:

{webhook-id}.{webhook-timestamp}.{raw body}

The signature is the base64 of the HMAC-SHA256 of that string — base64, not hex, which is the one difference from the legacy header below.

$body = file_get_contents('php://input');
$id   = $_SERVER['HTTP_WEBHOOK_ID'] ?? '';
$ts   = $_SERVER['HTTP_WEBHOOK_TIMESTAMP'] ?? '';

// Reject anything stale BEFORE checking the signature. A signature stays valid
// forever, so without this a delivery someone captured can be replayed at you
// indefinitely and it will verify perfectly every time.
if (!$ts || abs(time() - (int) $ts) > 300) {
    http_response_code(400);
    exit;
}

$expected = 'v1,' . base64_encode(hash_hmac('sha256', "$id.$ts.$body", $YOUR_KEY, true));

// The header is a space-delimited list so a key rotation can send more than one.
// Split it and accept if any entry matches — do not compare the whole header.
$sent = explode(' ', $_SERVER['HTTP_WEBHOOK_SIGNATURE'] ?? '');
$ok   = false;

foreach ($sent as $candidate) {
    if (hash_equals($expected, $candidate)) {
        $ok = true;
    }
}

if (!$ok) {
    http_response_code(401);
    exit;
}

Your signing secret

A webhook saved without a secret gets one in the form whsec_ followed by base64. It is shown right after you save, and again whenever you press Show and copy on the webhook's row. Showing it is recorded: until someone has, the secret is shown in amber and the Health tab lists the webhook under Give each receiving system its secret.

For a whsec_ For a whsec_ secret the HMAC key is the decoded bytes, not the string you can see — that is what Standard Webhooks libraries expect, and they handle the decoding for you.

If your secret was typed in by hand rather than generated, it is used as-is: the raw bytes of the literal string. A site updated from 6.0 keeps its old secret on every webhook, so nothing changes for existing receivers.

Make a new secret on a webhook's row replaces its secret at once, after a confirmation. It invalidates signatures under both schemes, which is what rotation means: update the receiving system at the same time. Other webhooks are not affected.

Retries are signed again

Every attempt is signed when it is sent, not when the event happened:

  • webhook-timestamp is the time of this attempt, so a retry an hour later still passes a five-minute replay window. webhook-id and the body are unchanged.
  • The signature is made with the secret that is set at the time of the attempt. After you rotate the secret, retries of older events are signed with the new one. Switch your consumer to the new secret promptly, or accept both for a short while; otherwise the retries fail verification, are answered with an error, and are retried again until they give up.

The original header

X-NextRestaurant-Signature is unchanged and stays supported. Its value is sha256= followed by the hex HMAC-SHA256 of the raw body, keyed with your signing secret. Compute it over the bytes as received — re-serialising the JSON first will change them and the check will fail.

$body     = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $body, $YOUR_SECRET);

if (!hash_equals($expected, $_SERVER['HTTP_X_NEXTRESTAURANT_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}

This scheme has no timestamp in what it signs, so it cannot tell a replay from a fresh delivery on its own. That is the reason to prefer the Standard Webhooks header.

Unsigned deliveries

Since 6.1 every webhook has a secret, so deliveries are always signed. The delivery log still shows a Signed column; an unsigned row can only come from before the update.

All Extensions