Skip to content
Webhooks

Webhooks

Create a webhook with POST /v1/webhooks. The URL must be HTTPS outside local testing. The response returns the signing secret once; store it, because it is not shown again. A delivery is a POST with the event in X-Webhook-Event and the id in X-Webhook-Id.

Events

The current events are vetting.check.completed, vetting.license.expiring, order.submitted, order.shipped, order.delivered, vendor.inventory.updated and support.message.created. Subscribe only to the events you handle.

Verify the signature

Every delivery carries a signature header with t=<unix seconds>,v1=<hex HMAC-SHA256>. The signed value is t + "." + rawBody, keyed with the webhook secret. Compute the value over the raw body, compare it in constant time, and reject an old timestamp before you act.

The public header name is RollStamp-Signature.

js
import crypto from "node:crypto";

function verify(secret, header, rawBody, now = Math.floor(Date.now() / 1000)) {
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.split("=")),
  );
  if (!parts.t || !parts.v1) return false;
  if (Math.abs(now - Number(parts.t)) > 300) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  const got = Buffer.from(parts.v1);
  if (got.length !== Buffer.byteLength(expected)) return false;
  return crypto.timingSafeEqual(Buffer.from(expected), got);
}
Do not parse the body and re-encode it before verifying. Use the raw bytes that arrived. A proxy that rewrites JSON can break the signature.

Retries

A delivery that does not get a 2xx answer is retried after 1 minute, 5 minutes, 30 minutes and 2 hours. A fifth failed attempt marks the delivery failed; later events still deliver. Read recent deliveries with GET /v1/webhooks/{id}/deliveries. Make your handler idempotent on X-Webhook-Id.

Local testing

Local and http:// receivers work only when the server operator sets WEBHOOK_ALLOW_PRIVATE=1. That setting is for testing; do not use it in production.