Anton.Docs
Dashboard (opens in a new tab)
How it works

Webhook signing

The signature covers the exact bytes Anton sent, so it is the only proof a request came from Anton and not from someone who found your URL.

Every delivery is signed with an HMAC-SHA256 derived from your subscription's signing secret. Verify it on your endpoint before you act on anything in the payload.

Do not mark payouts as settled, release funds or update beneficiaries until the signature has verified.

The signature scheme

PropertyValue
AlgorithmHMAC-SHA256
EncodingLowercase hex
Signed string{timestamp}.{body}: the Unix timestamp, a literal dot and the raw request body
Header carrying the signatureX-Webhook-Signature, one or more comma-separated v1=<hex> entries
Header carrying the timestampX-Webhook-Timestamp (Unix seconds, UTC)
Secret formatwhsec_ followed by 64 hex characters

Every delivery also carries X-Webhook-ID (the event ID, for deduplication) and X-Webhook-Event (the event type).

X-Webhook-Signature can hold more than one signature, comma-separated, such as v1=abc...,v1=def.... During a secret rotation a delivery is signed with both the new and the previous secret. Check every v1= entry and accept the delivery if yours matches any one.

Verification steps

1
Read the raw request body

Capture the body as bytes before any JSON parsing or framework normalisation. Parsed-and-re-serialised JSON will not byte-match the string Anton signed.

2
Read the timestamp and signature headers

Pull X-Webhook-Timestamp and X-Webhook-Signature from the request. Split the signature header on commas and strip the v1= prefix from each entry. You receive one signature normally, or two during a rotation grace window.

3
Reject old timestamps

If the timestamp is more than 5 minutes (300 seconds) away from your server's current time, reject the request. This prevents replays of captured deliveries.

4
Compute the expected signature

Concatenate {timestamp}.{body}, compute HMAC-SHA256 over it using your subscription's signing secret, and hex-encode the result.

5
Compare in constant time against each entry

Compare your expected signature to each v1= entry using a constant-time comparison (hmac.compare_digest, crypto.timingSafeEqual, hash_equals, hmac.Equal) and accept the delivery if it matches any of them. Never use ==, which leaks timing information.

6
Acknowledge, then work

Return any 2xx to acknowledge receipt and do the real work from a queue. Anything else is retried, up to 5 attempts in all. See Webhook events.

Verification code

Each example reads the raw body, enforces the 5-minute window and compares in constant time.

// 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();
});

Rotating secrets

Every subscription has one signing secret. It is shown once, in the response that creates the subscription (POST /v1/webhooks) and in the response that rotates it. It cannot be read back, so store it in your secrets manager at once. If you lose it, rotate.

Rotate the secret
Shell
curl https://api.antonpayments.dev/v1/webhooks/whk_01HX.../secret/rotate \
  -X POST \
  -H "Authorization: DPoP $ANTON_ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF" \
  -H "Idempotency-Key: rotate-whk-01HX-2026-12-01"

Response:

JSON
{
  "id": "whk_01HX...",
  "object": "webhook_subscription",
  "secret": "whsec_...",
  "previous_secret_expires_at": "2026-12-02T14:03:22.104Z"
}

The response is the subscription with the new secret and previous_secret_expires_at, the end of the grace window.

The new secret takes effect at once and a 24-hour grace window opens. During it every delivery is signed with both secrets, so X-Webhook-Signature carries two v1= entries. Your endpoint keeps verifying with the old secret until you deploy the new one. After 24 hours the previous secret stops signing.

A retry of the same rotate request with the same Idempotency-Key returns the same subscription with secret set to null: the secret is never replayed.

Deploy the new secret within 24 hours of rotating.

If you are rotating because a secret leaked, the grace window keeps the leaked secret valid for 24 hours. Rotate with POST /v1/webhooks/{id}/secret/rotate?immediate=true to end it at once, and previous_secret_expires_at comes back null. Deliveries to an endpoint that has not picked up the new secret fail verification and retry.

Common pitfalls

  • Parsed JSON instead of raw bytes. Whitespace, key order and number formatting change when a framework parses and re-serialises the body. Capture the raw body first.
  • Header case. Read X-Webhook-Signature and X-Webhook-Timestamp through your framework's header API, not an exact-match dictionary lookup.
  • Assuming one signature. Split the header on commas, strip v1= from each entry and accept on any match.
  • A changed body. A proxy that appends a newline or transcodes the body invalidates the signature.
  • == or strcmp. Byte-by-byte equality leaks timing. Use a constant-time comparison.
  • No freshness check. Without it, one captured delivery can be replayed indefinitely. Reject anything more than 5 minutes from your clock.
  • Replying slowly. Acknowledge first and process asynchronously.

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