Webhooks

Signatures and retries

Every request is signed with the Standard Webhooks scheme, so any Standard Webhooks library can verify it.

Header Value Use
webhook-id the event id, the same on every retry dedupe on it
webhook-timestamp the attempt time, Unix seconds reject if more than 5 minutes off
webhook-signature v1, + base64 HMAC-SHA256 verify before you trust the body

The signature covers webhook-id, webhook-timestamp and the raw body joined with dots, keyed with the bytes you get by base64-decoding the part of your secret after whsec_.

The Standard Webhooks test vector

Part Value
secret whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw
webhook-id msg_p5jXN8AQM9LWM0D4loKWxJek
webhook-timestamp 1614265330
body {"test": 2432232314}
webhook-signature v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=

Signing these values must give this signature. The vector’s id is the standard’s own sample; Prio’s ids are UUIDs.

Node.js example

Verify against the raw request body, before any JSON parsing.

Node.js
import { Webhook } from "standardwebhooks";

const webhook = new Webhook(process.env.PRIO_WEBHOOK_SECRET);

app.post("/prio/webhooks", express.raw({ type: "application/json" }), (req, res) => {
  const event = webhook.verify(req.body, req.headers); // throws if forged or stale
  res.sendStatus(204);
  queue.add(event);
});

Retries

A request that fails is tried again after 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 10 hours — 8 attempts over about 27 hours — then dropped. A retry carries the same webhook-id. Events can arrive out of order; read the body, not the arrival order.