Verifying Signatures

Anyone who knows your URL can send a forged request. Always verify the signature before trusting an event.

Header format

X-Etalasse-Signature: t=1760151845,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

• t is the send time in Unix seconds.
• v1 is the hexadecimal signature. While a secret rotation overlap is open, the same header carries two v1 values.
• Every retry is re-signed with a fresh t.

How to compute it

1. Take t and all v1 values from the header.
2. Build the text t + . + the raw body (exactly the bytes you received).
3. Compute HMAC_SHA256(secret, text) as hex. The secret is the whole whsec_... string as UTF-8.
4. Compare it with each v1 using a constant-time comparison. One match is enough.
5. Reject if |now - t| is more than 300 seconds (5 minutes), to prevent replay.

(1) Join t, a dot and the raw body, (2) compute HMAC-SHA256 with the whole whsec_ secret, (3) compare with every v1 and check the 300-second window. Otherwise reject with 400.

(1) Join t, a dot and the raw body, (2) compute HMAC-SHA256 with the whole whsec_ secret, (3) compare with every v1 and check the 300-second window. Otherwise reject with 400.

Node.js example (Express)

const crypto = require('crypto');
const express = require('express');

const app = express();
const SECRET = process.env.ETALASSE_WEBHOOK_SECRET; // whsec_...
const TOLERANCE_SECONDS = 300;

function verify(rawBody, header) {
  if (!header) return false;
  const parts = header.split(',').map((p) => p.trim());
  const t = parts.find((p) => p.startsWith('t='))?.slice(2);
  const signatures = parts.filter((p) => p.startsWith('v1=')).map((p) => p.slice(3));
  if (!t || signatures.length === 0) return false;

  if (Math.abs(Date.now() / 1000 - Number(t)) > TOLERANCE_SECONDS) return false;

  const expected = crypto
    .createHmac('sha256', SECRET)
    .update(`${t}.${rawBody}`)
    .digest('hex');
  const expectedBuf = Buffer.from(expected, 'utf8');

  return signatures.some((sig) => {
    const sigBuf = Buffer.from(sig, 'utf8');
    return sigBuf.length === expectedBuf.length && crypto.timingSafeEqual(sigBuf, expectedBuf);
  });
}

// Important: read the RAW body, not parsed JSON.
app.post('/hooks/etalasse', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8');
  if (!verify(rawBody, req.get('X-Etalasse-Signature'))) {
    return res.status(400).send('invalid signature');
  }
  const event = JSON.parse(rawBody);
  // TODO: skip if event.id was already processed, then handle the event.
  res.status(200).send('ok');
});

app.listen(3000);

PHP example

<?php
$secret = getenv('ETALASSE_WEBHOOK_SECRET'); // whsec_...
$tolerance = 300;

$rawBody = file_get_contents('php://input'); // raw body
$header = $_SERVER['HTTP_X_ETALASSE_SIGNATURE'] ?? '';

$t = null;
$signatures = [];
foreach (explode(',', $header) as $part) {
    $part = trim($part);
    if (strpos($part, 't=') === 0) {
        $t = substr($part, 2);
    } elseif (strpos($part, 'v1=') === 0) {
        $signatures[] = substr($part, 3);
    }
}

$valid = false;
if ($t !== null && count($signatures) > 0 && abs(time() - (int) $t) <= $tolerance) {
    $expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
    foreach ($signatures as $sig) {
        if (hash_equals($expected, $sig)) {
            $valid = true;
            break;
        }
    }
}

if (!$valid) {
    http_response_code(400);
    exit('invalid signature');
}

$event = json_decode($rawBody, true);
// TODO: skip if $event['id'] was already processed, then handle the event.
http_response_code(200);
echo 'ok';

Common pitfalls

• Parsing the JSON and serializing it again. Whitespace, key order, or escaping change, so the signature no longer matches. Use the raw body.
• Middleware that alters the body (for example express.json() before your route). Put express.raw on the webhook route.
• A plain comparison (==). Use crypto.timingSafeEqual or hash_equals.
• Forgetting to check t. Without the 5-minute limit, old requests can be replayed.
• Reading only one v1. During rotation the matching signature may be the second one. Check them all.
• A wrong or truncated secret. Use the whole whsec_... string, not just the part after the prefix, and watch for stray spaces or newlines in environment variables.
• Server clock drift. Sync with NTP; otherwise every valid request can be rejected.
• Replying slowly. Reply 2xx quickly (8-second limit) and do the work in the background.

Related pages

• Overview and setup
• Secret rotation and testing
• Delivery, retries and failures