Skip to content
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

  1. Read the X-1Lookup-Signature header.
  2. Take the raw request body, before any JSON parsing.
  3. Compute the HMAC-SHA256 of that body with your signing secret.
  4. 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 id to 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.