In this section · 2 articles

Verify webhook signatures and handle retries

Check that a webhook really came from your Laramin, refuse replayed messages, accept deliveries during a secret rotation, and process each event once even when it arrives more than once.

Applies to
Webhook Engine 2.2 and later
Who can do this
Developer
On this page

Anyone who knows your endpoint's address can send it a request. Checking the signature proves a request came from your Laramin and wasn't changed on the way.

Before you start

  • You need the destination's signing secret: 32 letters and digits, created when the destination was added.
  • Find out whether the destination signs the timestamp. The Test Console shows Signs timestamp + payload (v2) or Signs payload only (v1), and every version 2 delivery has the header X-Laramin-Signature-Version: 2.

Getting the secret

No screen shows the signing secret. Someone with access to your Laramin's database must read it from the secret column of the destination's row in the we_webhook_destinations table (with your database's table prefix, if it has one). After a rotation, the previous secret is in old_secret. Store it like a password, for example in an environment variable, never in your code.

What is signed

VersionWhenSigned string
1Sign the timestamp is off. No X-Laramin-Signature-Version header.The raw request body
2Sign the timestamp is on. X-Laramin-Signature-Version: 2.The X-Laramin-Timestamp value, a dot, then the raw request body

X-Laramin-Signature is the lowercase hex HMAC-SHA256 of the signed string, using the current secret. After a rotation, X-Laramin-Signature-Secondary is the same, using the previous secret.

Steps

  1. Read the raw request body as bytes, before any JSON parsing.
  2. If the version is 2, check that X-Laramin-Timestamp is within a few minutes of your clock. Refuse it if not.
  3. Build the signed string for the version.
  4. Compute HMAC-SHA256 of it with each secret you hold, as lowercase hex.
  5. Compare each result with X-Laramin-Signature and, if present, X-Laramin-Signature-Secondary, using a constant-time comparison. Accept if any pair matches.
  6. Answer 2xx at once, then process the event, skipping it if you've seen it before.

Example: Node.js with Express

JavaScript
const crypto = require('node:crypto');
const express = require('express');

const app = express();

// Current secret, plus the previous one while a rotation is under way.
const SECRETS = [process.env.LARAMIN_WEBHOOK_SECRET, process.env.LARAMIN_WEBHOOK_PREVIOUS_SECRET].filter(Boolean);
const TOLERANCE_SECONDS = 300;

// express.raw keeps the body as the exact bytes that were signed.
app.post('/laramin/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const body = req.body; // a Buffer
  const timestamp = req.get('X-Laramin-Timestamp') || '';
  const version = req.get('X-Laramin-Signature-Version') || '1';

  let signed = body;
  if (version === '2') {
    const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
    if (!/^\d+$/.test(timestamp) || age > TOLERANCE_SECONDS) {
      return res.status(400).end(); // too old, or from the future: possibly a replay
    }
    signed = Buffer.concat([Buffer.from(timestamp + '.'), body]);
  }

  const received = [req.get('X-Laramin-Signature'), req.get('X-Laramin-Signature-Secondary')]
    .filter(Boolean)
    .map((value) => Buffer.from(value));

  const valid = SECRETS.some((secret) => {
    const expected = Buffer.from(crypto.createHmac('sha256', secret).update(signed).digest('hex'));
    return received.some((sig) => sig.length === expected.length && crypto.timingSafeEqual(sig, expected));
  });

  if (!valid) {
    return res.status(401).end();
  }

  res.status(204).end(); // answer within 10 seconds

  const event = JSON.parse(body.toString('utf8'));
  // Hand `event` to a queue, skipping duplicates (see below).
});

app.listen(3000);

Example: Python with Flask

Python
import hashlib, hmac, os, time
from flask import Flask, abort, request

app = Flask(__name__)
SECRETS = [s for s in (os.environ.get("LARAMIN_WEBHOOK_SECRET"),
                       os.environ.get("LARAMIN_WEBHOOK_PREVIOUS_SECRET")) if s]

@app.post("/laramin/webhooks")
def laramin_webhook():
    body = request.get_data()  # raw bytes
    timestamp = request.headers.get("X-Laramin-Timestamp", "")
    if request.headers.get("X-Laramin-Signature-Version", "1") == "2":
        if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
            abort(400)
        signed = timestamp.encode() + b"." + body
    else:
        signed = body

    received = [h for h in (request.headers.get("X-Laramin-Signature"),
                            request.headers.get("X-Laramin-Signature-Secondary")) if h]
    for secret in SECRETS:
        expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
        if any(hmac.compare_digest(expected, sig) for sig in received):
            return "", 204  # then process the event, skipping duplicates
    abort(401)

Common mistakes

  • Verifying parsed JSON. Frameworks that parse JSON for you lose the exact bytes. The body escapes / as \/ and non-ASCII characters as \u sequences, so encoding it again gives a different string and the signature never matches.
  • Comparing with ==. Use a constant-time function: crypto.timingSafeEqual, hmac.compare_digest or PHP's hash_equals.
  • Checking only X-Laramin-Signature. After a rotation, your secret may only match X-Laramin-Signature-Secondary until you switch to the new one.
  • Accepting version 1 forever. Version 1 doesn't sign the timestamp, so a captured delivery passes again whenever it's resent. Once the destination sends version 2, refuse requests without X-Laramin-Signature-Version: 2.

Retries and timing

Your Laramin treats any 2xx answer within 10 seconds as delivered. Anything else is retried:

AttemptSent
1When the event happens, or later if the destination's rate limit spaces it out
25 seconds after attempt 1 fails
315 seconds after attempt 2 fails
41 minute after attempt 3 fails
55 minutes after attempt 4 fails. If it fails too, the delivery is abandoned.

An administrator can send any delivery again later with Redeliver, as a new delivery with 5 attempts of its own. After 20 failed attempts in a row, across all deliveries, the destination is suspended and receives nothing until an administrator turns it back on.

With version 2, every attempt, retry and redelivery is signed at the moment it's sent, so X-Laramin-Timestamp is always fresh. Your tolerance only needs to cover clock differences and network time.

Handle duplicates

The same event can reach you more than once: when your endpoint did the work but answered too late, when the network dropped your answer, or when an administrator redelivers it. Deliveries carry no delivery id, so build your own key from the content:

  • Parse the body, sort the keys of every object, encode it again and take a SHA-256 hash. Record keys you've processed, and skip a body whose key you've already seen.
  • Don't hash the raw bytes for this. Automatic retries send the same bytes, but a redelivery is rebuilt from the delivery log. On a MySQL database, the log reorders the payload's keys, so a redelivered body has the same values with its keys in a different order. The signature still matches, because it's made over the bytes actually sent.
  • The body's timestamp (record events) or occurred_at (Headless CMS events) stays the same on retries and redeliveries, so two genuinely separate events rarely produce the same key.
  • Keep keys for at least a few days. Redeliveries can come long after the first attempt.
  • Treat the payload as a notice, and read the current state from your Laramin if order matters. Deliveries can arrive out of order, for example when an earlier one is being retried. For record events, compare data.updated_at; for Headless CMS events, compare content_version.

To check your receiver end to end, send a test from the Test Console. Its Request headers tab shows exactly what was sent.