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_ 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
| Version | When | Signed string |
|---|---|---|
| 1 | Sign the timestamp is off. No X- header. | The raw request body |
| 2 | Sign the timestamp is on. X-. | The X- value, a dot, then the raw request body |
X- is the lowercase hex HMAC-SHA256 of the signed string, using the current secret. After a rotation, X- is the same, using the previous secret.
Steps
- Read the raw request body as bytes, before any JSON parsing.
- If the version is
2, check thatX-is within a few minutes of your clock. Refuse it if not.Laramin- Timestamp - Build the signed string for the version.
- Compute HMAC-SHA256 of it with each secret you hold, as lowercase hex.
- Compare each result with
X-and, if present,Laramin- Signature X-, using a constant-time comparison. Accept if any pair matches.Laramin- Signature- Secondary - Answer
2xxat once, then process the event, skipping it if you've seen it before.
Example: Node.js with Express
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
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
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
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\usequences, so encoding it again gives a different string and the signature never matches. - Comparing with
==. Use a constant-time function:crypto.,timingSafeEqual hmac.or PHP'scompare_digest hash_equals. - Checking only
X-. After a rotation, your secret may only matchLaramin- Signature X-until you switch to the new one.Laramin- Signature- Secondary - 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:
| Attempt | Sent |
|---|---|
| 1 | When the event happens, or later if the destination's rate limit spaces it out |
| 2 | 5 seconds after attempt 1 fails |
| 3 | 15 seconds after attempt 2 fails |
| 4 | 1 minute after attempt 3 fails |
| 5 | 5 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- 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) oroccurred_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, comparecontent_version.
To check your receiver end to end, send a test from the Test Console. Its Request headers tab shows exactly what was sent.
Thanks. That helps us decide what to write next.
Thanks for telling us what was missing.
You already answered for this article today. Thanks.
We got a lot of answers from your network just now. Try again in a few minutes.
We couldn't send that. Check your connection and try again.
Links in this article
Printed from help.bsscn.com. The online article may have changed since.