Pages · Webhooks

Webhooks

Signed event deliveries, verification, retries and replays.

Tapebloom sends each event as a signed JSON POST to your enabled endpoints in the event's mode. Create one with POST /webhook_endpoints:

curl -sS "https://api.tapebloom.com/v1/webhook_endpoints" \
  -H "Authorization: Bearer $TAPEBLOOM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: endpoint-main-v1" \
  -d '{ "url": "https://example.com/tapebloom/webhooks", "event_types": ["order.needs_attention", "order.complete"] }'

The response includes the signing secret (whsec_…). Store it, for example as TAPEBLOOM_WEBHOOK_SECRET; it is not shown again except in a replay of the same request. Omit event_types to receive every type. The URL must be https (in test mode, http://localhost and http://127.0.0.1 also work). At most 10 endpoints can be enabled per mode.

Event types

order.awaiting_payment, order.cancelled, order.complete, order.exception_opened, order.materials_hold, order.needs_attention, order.received, order.released, order.validating, payment.canceled, payment.failed, payment.requires_action, payment.succeeded, refund.failed, refund.succeeded, shipment.delivered, shipment.returned, shipment.shipped

The delivery

{
  "id": "1a7e3c90-4f2b-4d6a-8c15-9e0b7d2f3a64",
  "type": "order.needs_attention",
  "occurred_at": "…",
  "environment": "test",
  "order_id": "c3e8a1f4-2b6d-4f7a-9e05-8d1b3c7a2e96",
  "sequence": 3,
  "data": { "order_id": "…", "object": "order", "object_id": "…", "state": "needs_attention", "reason": "…" }
}

The headers carry Tapebloom-Signature and Tapebloom-Event-Id. The body is the same bytes on every attempt for one event.

Verifying the signature

Tapebloom-Signature: t=<unix seconds>,v1=<hex>. Each v1 is an HMAC-SHA256 of ${t}.${rawBody} with your endpoint's signing secret. During a secret rotation there is one v1 per active secret. Every attempt is freshly signed with a new t.

  • Verify against the raw body, before parsing it.
  • Compare in constant time, and accept a match on any v1.
  • Reject timestamps more than 5 minutes from now, either way.
Verifying a delivery (TypeScript, Node)
import { createHmac, timingSafeEqual } from "node:crypto";

const TOLERANCE_SECONDS = 300;

export function verifyTapebloomSignature(rawBody: string, header: string | null, secrets: string[]): boolean {
  if (!header) return false;
  let t: number | undefined;
  const candidates: Buffer[] = [];
  for (const part of header.split(",")) {
    const [key, value] = part.trim().split("=", 2);
    if (key === "t" && /^\d{1,12}$/.test(value ?? "")) t = Number(value);
    else if (key === "v1" && /^[0-9a-f]{64}$/.test(value ?? "")) candidates.push(Buffer.from(value, "hex"));
  }
  if (t === undefined || candidates.length === 0) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > TOLERANCE_SECONDS) return false;
  return secrets.some((secret) => {
    const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
    return candidates.some((c) => c.length === expected.length && timingSafeEqual(c, expected));
  });
}

// A Next.js route handler (any Fetch API runtime works the same way).
export async function POST(request: Request) {
  const rawBody = await request.text();
  const ok = verifyTapebloomSignature(rawBody, request.headers.get("tapebloom-signature"), [
    process.env.TAPEBLOOM_WEBHOOK_SECRET!,
  ]);
  if (!ok) return Response.json({ error: "bad_signature" }, { status: 401 });
  const event = JSON.parse(rawBody);
  // Record event.id and apply its effects in ONE database transaction;
  // if the id is already recorded, it is a repeat: do nothing.
  return Response.json({ received: true });
}

Duplicates and ordering

  • The same event may arrive more than once, each time freshly signed. Record its id in the same database transaction as its effects, and acknowledge a repeat with 2xx without repeating them.
  • There is no global ordering. Use sequence per order_id, and GET /events?order_id=…&after_sequence=… to fill gaps.
  • For effects outside your database (an email, another API), pass the event id as that service's idempotency key.

Retries

Answer with a 2xx within 10 seconds. Redirects are not followed. A failed delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 5 hours, then every 10 hours, for up to 3 days; then it is abandoned. Delivery states: pending, delivered, abandoned.

  • GET /webhook_endpoints/{id}/deliveries lists an endpoint's deliveries; GET /webhook_deliveries/{id} shows every attempt with its status code or error.
  • POST /webhook_deliveries/{id}/replay sends a delivery again now, with a new 3-day retry window. The event's id, sequence and body are unchanged.
  • POST /webhook_endpoints/{id}/disable and /enable set the endpoint's state; both are safe to repeat and take no Idempotency-Key.

Rotating the secret

POST /webhook_endpoints/{id}/rotate_secret returns a new secret. The old one keeps signing alongside it for overlap_hours (default 24, 0 to 168), so each delivery carries both signatures and you can switch without a gap. Verify against both secrets until you have deployed the new one.