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.
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
idin the same database transaction as its effects, and acknowledge a repeat with 2xx without repeating them. - There is no global ordering. Use
sequenceperorder_id, andGET /events?order_id=…&after_sequence=…to fill gaps. - For effects outside your database (an email, another API), pass the event
idas 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}/deliverieslists an endpoint's deliveries;GET /webhook_deliveries/{id}shows every attempt with its status code or error.POST /webhook_deliveries/{id}/replaysends a delivery again now, with a new 3-day retry window. The event's id, sequence and body are unchanged.POST /webhook_endpoints/{id}/disableand/enableset the endpoint's state; both are safe to repeat and take noIdempotency-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.