Anton.Docs
Dashboard (opens in a new tab)

Verify webhook signatures

The signature covers the exact bytes Anton sent, so a body your framework has already parsed cannot be verified. Read the raw request first.

Anyone who finds your webhook URL can post to it. The signature is the only thing that separates an Anton delivery from a forgery, so a handler that updates a payout before it checks the signature has no security at all. Webhook signing defines the scheme; this page is the handler.

Before you begin

What you check

Every delivery carries X-Webhook-Timestamp (Unix seconds) and X-Webhook-Signature. Anton computes an HMAC-SHA256 over the string {timestamp}.{raw body} with your secret and sends it as lowercase hex, prefixed v1=.

Your handler does the same sum and compares. Do these steps in this order.

1
Read the raw body

Take the bytes before any JSON parsing. Parse and re-serialise, and whitespace, key order and number formatting change, so a genuine delivery fails. In Express that means express.raw() on this route, not express.json().

2
Reject a stale timestamp

Refuse a delivery whose timestamp is more than 300 seconds from your clock, in either direction. Without this window, one captured delivery can be replayed forever.

3
Compute and compare

Hex-encode your HMAC and compare it to every v1= entry in the header with a constant-time function. Accept on any match. A plain == leaks how many leading characters were right.

4
Acknowledge, then work

Return a 2xx within 30 seconds of the request, and do the real work from a queue. A slower answer counts as a failed delivery.

The header can hold two signatures, such as v1=abc...,v1=def.... That happens for 24 hours after a secret rotation, when each delivery is signed with the new and the previous secret. A rotation with immediate=true has no overlap. A handler that reads one signature rejects every delivery in that window.

The handler

The first four examples read the raw body, enforce the 300-second window and compare in constant time. The shell script is for checking a captured delivery by hand. Set the secret in WEBHOOK_SECRET.

// Node 18+, Express. express.raw() gives req.body as a Buffer.
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.WEBHOOK_SECRET; // whsec_...

app.post("/webhooks/anton", express.raw({ type: "application/json" }), (req, res) => {
  const timestamp = req.header("X-Webhook-Timestamp");
  const signatures = (req.header("X-Webhook-Signature") || "")
    .split(",")
    .map((s) => s.trim().replace(/^v1=/, ""))
    .filter(Boolean);
  if (!timestamp || signatures.length === 0) return res.status(400).send("missing headers");

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

  // Hash the raw bytes. Decoding them to a string first can change them.
  const expected = crypto
    .createHmac("sha256", SECRET)
    .update(Buffer.concat([Buffer.from(`${timestamp}.`), req.body]))
    .digest();

  const valid = signatures.some((sig) => {
    const actual = Buffer.from(sig, "hex");
    return actual.length === expected.length && crypto.timingSafeEqual(expected, actual);
  });
  if (!valid) return res.status(400).send("invalid signature");

  // Queue req.body for a worker, then acknowledge.
  res.status(200).send();
});

When it fails

If every delivery is rejected, check these first.

  • A parsed body. The framework read the JSON before your handler did. Mount the raw reader on this route only.
  • A body that was changed on the way. A proxy that adds a trailing newline or changes the encoding invalidates the signature.
  • The wrong secret. Rotation issues a new whsec_ value. During the 24-hour window the header carries a signature for each secret, and after it only the new one.
  • A clock that has drifted. Every delivery looks stale. Check your server's time before you check anything else.
  • == or strcmp. It works in a test and leaks timing in production. Use crypto.timingSafeEqual, hmac.compare_digest, hash_equals or hmac.Equal.

The headers Anton sent, signature included, are kept with each delivery attempt. GET /v1/webhooks/{id}/deliveries returns them next to what your server answered, so you can recompute the signature from a real attempt.

A verified delivery can still arrive twice. The signature proves who sent it, not that you have not seen it. Deduplicate on X-Webhook-ID.

Next

Something wrong or missing here? Open an issue (opens GitHub in a new tab) ↗