Verifying signatures

The signing scheme, code in three languages, and test vectors.

Anyone can POST JSON at your endpoint. The signature is what tells you a delivery is ours — verify it before you read the body, not after.

The scheme

HMAC-SHA256 over "{timestamp}.{rawBody}", keyed with your endpoint's signing secret, hex-encoded, and sent in one header:

POST /webhooks/salaf HTTP/1.1
Content-Type: application/json
X-Salaf-Signature: t=1754899200,v1=dd3c17ef08611a833fd18718fb90d48d278db0f7f1ced1c1812aad359a718de8
X-Salaf-Event: order.created
X-Salaf-Event-Id: evt_01J4X8G9ABCDEFGHJKMNPQRSTV

Part	Meaning
`t`	The Unix timestamp, in seconds, at which the request was signed.
`v1`	A hex HMAC-SHA256 digest. `v1` names the scheme, not the payload version — a future `v2=` would mean a different algorithm, and receivers that only understand `v1` would keep working.

There may be two v1= values. That is a secret rotation in progress: the old secret keeps co-signing for 24 hours so you can deploy the new one at your own pace. Accept the delivery if either matches — see Rotating a secret.

Three details carry the whole security argument, and skipping any one of them produces code that looks like it verifies and does not:

The timestamp is inside the signed string. Signing the body alone would let anyone who captured one delivery replay it forever with a fresh t=, because the header would still verify. Because t is signed, changing it invalidates the signature — which is what makes your freshness check meaningful rather than decorative.
The raw bytes are signed, not a parsed object. See the raw-body trap.
The comparison must be constant-time. a === b on a digest leaks, through timing, how many leading characters an attacker guessed right. That turns forging a 64-character hex string from impossible into a few thousand requests.

Verifying

import crypto from "node:crypto";

const TOLERANCE_SECONDS = 300; // 5 minutes

/**
 * @param rawBody the EXACT bytes we sent, as a string or Buffer — never a
 *                re-serialised object.
 */
export function verifySalafSignature(rawBody, header, secret) {
  if (!header) return false;

  let timestamp = null;
  const signatures = [];
  for (const part of header.split(",")) {
    const [key, value] = part.split("=");
    if (key?.trim() === "t") timestamp = Number(value?.trim());
    if (key?.trim() === "v1") signatures.push(value?.trim());
  }
  if (!Number.isFinite(timestamp) || signatures.length === 0) return false;

  // Reject anything captured and replayed later. The timestamp is INSIDE the
  // signed string, so an attacker cannot simply put a fresh one in the header.
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > TOLERANCE_SECONDS) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`, "utf8")
    .digest("hex");

  // During a secret rotation there are TWO v1= values; either may match.
  return signatures.some((candidate) => timingSafeEqual(expected, candidate));
}

// Never use === on a signature: the early exit leaks, through timing, how
// many leading characters an attacker guessed right.
function timingSafeEqual(a, b) {
  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
}

import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300  # 5 minutes


def verify_salaf_signature(raw_body: bytes, header: str, secret: str) -> bool:
    """raw_body is the exact request body — bytes, not a parsed dict."""
    if not header:
        return False

    timestamp = None
    signatures = []
    for part in header.split(","):
        key, _, value = part.partition("=")
        if key.strip() == "t":
            timestamp = value.strip()
        elif key.strip() == "v1":
            signatures.append(value.strip())

    if timestamp is None or not signatures:
        return False

    # Replay window. The timestamp is signed, so it cannot be swapped.
    if abs(int(time.time()) - int(timestamp)) > TOLERANCE_SECONDS:
        return False

    signed_payload = timestamp.encode() + b"." + raw_body
    expected = hmac.new(
        secret.encode(), signed_payload, hashlib.sha256
    ).hexdigest()

    # compare_digest, never ==: a plain comparison leaks the match length.
    # Two v1= values appear during a rotation; either may match.
    return any(hmac.compare_digest(expected, s) for s in signatures)

<?php

const SALAF_TOLERANCE_SECONDS = 300; // 5 minutes

/** $rawBody must be the exact request body, not a re-encoded array. */
function verify_salaf_signature(string $rawBody, ?string $header, string $secret): bool
{
    if ($header === null || $header === '') {
        return false;
    }

    $timestamp = null;
    $signatures = [];
    foreach (explode(',', $header) as $part) {
        [$key, $value] = array_pad(explode('=', $part, 2), 2, null);
        $key = trim((string) $key);
        if ($key === 't') {
            $timestamp = trim((string) $value);
        } elseif ($key === 'v1') {
            $signatures[] = trim((string) $value);
        }
    }

    if ($timestamp === null || $signatures === []) {
        return false;
    }

    // Replay window — the timestamp is part of what was signed.
    if (abs(time() - (int) $timestamp) > SALAF_TOLERANCE_SECONDS) {
        return false;
    }

    $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);

    // hash_equals, never ===. Two signatures ride along during a rotation.
    foreach ($signatures as $candidate) {
        if (hash_equals($expected, $candidate)) {
            return true;
        }
    }

    return false;
}

Then reject the delivery if verification fails. A 400 is the right answer: we will retry it, but no number of retries will make an unsigned request valid, and the failure is visible in the merchant's delivery log where they can act on it.

The five-minute window

Reject any delivery whose t is more than 300 seconds from your own clock, in either direction. We do not enforce this — you do, and the code above shows where.

That window is a compromise between two real problems: a captured request should not be replayable tomorrow, and two machines nobody synchronised will disagree by a few seconds. Five minutes is comfortably more than clock skew and comfortably less than useful to an attacker.

The raw-body trap

This is the single most common way a working integration breaks intermittently, so it is worth stating bluntly: verify against the exact bytes you received.

Re-serialising JSON produces different bytes on different platforms — key order, unicode escaping, whitespace, number formatting. A receiver that verifies against JSON.stringify(req.body) will match on most payloads and fail on the ones containing a Bengali product name or a decimal that round-trips differently. It looks like an intermittent network problem and it is not.

Every popular framework parses the body for you by default, so getting the raw bytes takes one deliberate line:

import express from "express";

const app = express();

// Option A — keep the parsed body AND capture the raw bytes beside it.
app.use(
  express.json({
    verify: (req, _res, buffer) => {
      req.rawBody = buffer;
    },
  }),
);

// Option B — for the webhook route only, do not parse at all.
app.post(
  "/webhooks/salaf",
  express.raw({ type: "application/json" }),
  (req, res) => {
    // req.body is a Buffer here — exactly the bytes we signed.
    const ok = verifySalafSignature(
      req.body,
      req.get("X-Salaf-Signature"),
      process.env.SALAF_WEBHOOK_SECRET,
    );
    if (!ok) return res.sendStatus(400);

    const event = JSON.parse(req.body.toString("utf8"));
    res.sendStatus(200);
    void handleLater(event);
  },
);

// What NOT to do: JSON.stringify(req.body). Re-serialising changes key
// order, unicode escaping and whitespace, so the digest will differ from
// ours on some payloads and match on others — the worst kind of bug.

# Django — request.body is the raw bytes, before any parsing.
from django.http import HttpResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_POST


@csrf_exempt
@require_POST
def salaf_webhook(request):
    ok = verify_salaf_signature(
        request.body,  # bytes — do NOT use request.POST or json.dumps()
        request.headers.get("X-Salaf-Signature"),
        settings.SALAF_WEBHOOK_SECRET,
    )
    if not ok:
        return HttpResponse(status=400)

    event = json.loads(request.body)
    enqueue_event(event)  # queue it; answer immediately
    return HttpResponse(status=200)


# Flask — request.get_data() with cache=True, so calling .json later still
# works. request.get_json() alone would give you a dict you cannot verify.
@app.post("/webhooks/salaf")
def salaf_webhook_flask():
    raw = request.get_data(cache=True)
    if not verify_salaf_signature(
        raw, request.headers.get("X-Salaf-Signature"), SECRET
    ):
        return "", 400
    enqueue_event(json.loads(raw))
    return "", 200

<?php

// routes/web.php — exclude the webhook route from CSRF verification.
Route::post('/webhooks/salaf', [SalafWebhookController::class, 'handle'])
    ->withoutMiddleware([\App\Http\Middleware\VerifyCsrfToken::class]);

class SalafWebhookController extends Controller
{
    public function handle(Request $request)
    {
        // getContent() is the raw body. $request->all() and $request->json()
        // are parsed structures — re-encoding them changes the bytes.
        $raw = $request->getContent();

        $ok = verify_salaf_signature(
            $raw,
            $request->header('X-Salaf-Signature'),
            config('services.salaf.webhook_secret'),
        );

        if (! $ok) {
            return response()->noContent(400);
        }

        $event = json_decode($raw, true);
        SalafEventJob::dispatch($event); // queue, then answer

        return response()->noContent(200);
    }
}

Verify your implementation

These vectors are pinned by a test in our own codebase, so they cannot drift away from what the server does. Run your verification code against them before you point it at a live endpoint — if it disagrees here, it will disagree in production, and you will be debugging it against real orders.


Secret	`whsec_TestSecretForDocumentationVectorsOnly1`
Timestamp	`1754899200`
Raw body	`{"id":"evt_01J4X8G9ABCDEFGHJKMNPQRSTV","type":"salaf.ping"}`
Signed string	`1754899200.{"id":"evt_01J4X8G9ABCDEFGHJKMNPQRSTV","type":"salaf.ping"}`
Expected `v1`	`dd3c17ef08611a833fd18718fb90d48d278db0f7f1ced1c1812aad359a718de8`
Full header	`t=1754899200,v1=dd3c17ef08611a833fd18718fb90d48d278db0f7f1ced1c1812aad359a718de8`

import crypto from "node:crypto";

const secret = "whsec_TestSecretForDocumentationVectorsOnly1";
const timestamp = 1754899200;
const body = '{"id":"evt_01J4X8G9ABCDEFGHJKMNPQRSTV","type":"salaf.ping"}';

const signature = crypto
  .createHmac("sha256", secret)
  .update(`${timestamp}.${body}`, "utf8")
  .digest("hex");

console.log(signature);
// dd3c17ef08611a833fd18718fb90d48d278db0f7f1ced1c1812aad359a718de8

console.assert(
  signature === "dd3c17ef08611a833fd18718fb90d48d278db0f7f1ced1c1812aad359a718de8",
  "Your signing does not match Salaf's. Check that you sign " +
    "`timestamp + '.' + rawBody` and hex-encode the digest.",
);

import hashlib
import hmac

secret = "whsec_TestSecretForDocumentationVectorsOnly1"
timestamp = "1754899200"
body = '{"id":"evt_01J4X8G9ABCDEFGHJKMNPQRSTV","type":"salaf.ping"}'

signature = hmac.new(
    secret.encode(),
    timestamp.encode() + b"." + body.encode(),
    hashlib.sha256,
).hexdigest()

print(signature)
# dd3c17ef08611a833fd18718fb90d48d278db0f7f1ced1c1812aad359a718de8

assert signature == (
    "dd3c17ef08611a833fd18718fb90d48d278db0f7f1ced1c1812aad359a718de8"
), "Your signing does not match Salaf's."

<?php

$secret = 'whsec_TestSecretForDocumentationVectorsOnly1';
$timestamp = '1754899200';
$body = '{"id":"evt_01J4X8G9ABCDEFGHJKMNPQRSTV","type":"salaf.ping"}';

$signature = hash_hmac('sha256', $timestamp . '.' . $body, $secret);

echo $signature . PHP_EOL;
// dd3c17ef08611a833fd18718fb90d48d278db0f7f1ced1c1812aad359a718de8

assert($signature === 'dd3c17ef08611a833fd18718fb90d48d278db0f7f1ced1c1812aad359a718de8');

If your digest matches, your signing is correct. The remaining things to check in your own code are the ones the vector cannot exercise: that you compare in constant time, that you enforce the timestamp window, and that you accept either v1 value when two are present.

Where the secret lives

Shown once, when the endpoint is created, and again only when you rotate it. It starts with whsec_.
Store it like a password — an environment variable or a secret manager, never in source. The whsec_ prefix exists so secret scanners can catch it if it does end up in a commit.
One secret per endpoint. If you receive events at two URLs, they have two different secrets, and verifying with the wrong one fails exactly as if the request were forged.
We cannot show it to you again. It is encrypted rather than hashed (signing needs the plaintext back), but there is no screen and no support process that prints it. If you lose it, rotate.