Webhooks
Webhook security
Check the signature on every webhook request before you act on it. It proves the request came from 1lookup.dev and that the body was not changed on the way.
Signing secret
Each workspace has one signing secret, used to sign every webhook request. View and rotate it under Settings, Advanced in the dashboard.
Signature header
Each request carries an X-1Lookup-Signature header: the HMAC-SHA256 of the raw request body, keyed with your signing secret and written as lowercase hex.
Header
X-1Lookup-Signature: 5f2b9c0d7e41a8c3...How to verify
- Read the
X-1Lookup-Signatureheader. - Take the raw request body, before any JSON parsing.
- Compute the HMAC-SHA256 of that body with your signing secret.
- Compare the two values with a timing-safe function, and reject the request if they differ.
Implementation
import crypto from "node:crypto";
import express from "express";
const app = express();
const secret = process.env.LOOKUP_WEBHOOK_SECRET;
// Read the raw body. The signature is computed over the exact bytes we sent.
app.post("/hooks/1lookup", express.raw({ type: "application/json" }), (req, res) => {
const received = req.get("X-1Lookup-Signature") ?? "";
const expected = crypto.createHmac("sha256", secret).update(req.body).digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(received);
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
return res.status(401).send("Invalid signature");
}
const event = JSON.parse(req.body.toString("utf8"));
// Queue the event, then acknowledge.
res.sendStatus(200);
});Good practice
- Verify against the raw bytes. A body that was parsed and serialized again will not match.
- Use a timing-safe comparison, as in the examples above, instead of a plain equality check.
- Use the event
idto ignore an event you have already processed. See delivery and retries. - Acknowledge with a 2xx status within 10 seconds, and do slow work after you respond.