A signed message travelling from a captured page to a server
DevelopersWebhooksSecurity

How to verify a webhook signature before you trust a capture event

A webhook endpoint is a public address that anyone can send a POST to. The signature is how your code tells our delivery from somebody else's guess.

· 5 min read

The risk

Why check at all

When a capture finishes or a page changes, we POST a small JSON body to the address you registered. Your code probably acts on it: files a ticket, posts to a channel, starts a deploy check. If the address is all that protects it, anyone who learns the address can trigger the same actions with a body they wrote themselves.

Every delivery is therefore signed with a secret only you and we know. Checking it takes about fifteen lines.

The format

What is signed

Each delivery carries four headers:

X-WSW-Event: capture.succeeded
X-WSW-Delivery: 0b2e6f5a-8c31-4b2f-9a6d-9f5a1e2b7c44
X-WSW-Attempt: 1
X-WSW-Signature: t=1767225600,v1=c03a0b18...58ef9

X-WSW-Signature has two parts: t, the time of this attempt in Unix seconds, and v1, a hex HMAC-SHA256. The signed text is the timestamp, a full stop and the raw request body. The secret starts with whsec_ and is shown in the app under Developer Tools → Webhooks.

The code

The check, in Node.js

Express
import crypto from "node:crypto";

// express.raw: the signature is over the bytes we sent, so do not parse first.
app.post("/your-endpoint", express.raw({ type: "application/json" }), (req, res) => {
    const header = req.get("X-WSW-Signature") ?? "";
    const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
    const timestamp = Number(parts.t);

    if (!Number.isFinite(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > 300) {
        return res.status(400).send("stale");
    }

    const expected = crypto
        .createHmac("sha256", process.env.WSW_WEBHOOK_SECRET)
        .update(`${parts.t}.${req.body.toString("utf8")}`)
        .digest("hex");

    const ok =
        parts.v1?.length === expected.length &&
        crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));

    if (!ok) return res.status(401).send("bad signature");

    res.status(200).end(); // answer first
    enqueue(JSON.parse(req.body.toString("utf8"))); // work afterwards
});

To test your own implementation in another language, these values must agree:

A worked example
secret = whsec_testsecret
t      = 1767225600
body   = {"id":"a","type":"ping"}
signed = 1767225600.{"id":"a","type":"ping"}
v1     = c03a0b1898f8ab18939c00d5afc47d131bbd24ac9d4db23038412cfc26d58ef9
Pitfalls

Three mistakes that break it

  1. Signing the object, not the bytes. A framework that parses JSON for you has already thrown the original bytes away. Parsing and re-serialising gives different bytes and a different signature. Read the raw body before anything else touches it.
  2. Skipping the timestamp. Without it, a delivery someone recorded can be sent again next month and will still verify. Refuse anything more than five minutes old.
  3. Comparing with ==. An ordinary string comparison stops at the first different character, and the time it takes leaks how much matched. Use a constant-time comparison such as crypto.timingSafeEqual.
Reliability

After the check

  • Answer fast. We wait ten seconds for a 2xx. Acknowledge first and do the work afterwards, from a queue.
  • Expect duplicates. A delivery is retried when we are unsure it arrived, and the retry carries the same id. Use it as the de-duplication key.
  • Know the retry schedule. Each delivery gets six attempts: at once, then after about 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours.
  • Rotate without downtime. A new secret takes effect immediately, so accept both the old and the new one for a few minutes while your deployment catches up.
The file is never in the webhook
The body carries ids and status, not the image and not a download link. When you want the capture, fetch it through the API with your own key. A link in a webhook body would outlive the delivery and leak the first time a log was shared.
Questions

FAQ

Why does my signature never match?

Almost always because the body was parsed before it was checked. The signature is over the exact bytes that were sent. Parsing the JSON and writing it out again produces different bytes, and so a different signature. Read the raw body first.

Why is there a timestamp in the signature?

So that a delivery someone has copied is useless a few minutes later. The timestamp is inside the signed text, so it cannot be changed, and your code refuses anything older than five minutes.

Can the same event arrive twice?

Yes. A delivery we are unsure about is retried, so the same id can arrive more than once. Keep the ids you have handled and skip repeats.

Does the webhook contain the screenshot?

No. The body carries ids and status, never the file or a download link. Fetch the capture through the API with your own key when you want it.