Webhooks, recovery, and errors

Verify the signature with the environment secret, record the event identifier, and respond quickly. Process idempotently: the same webhook may arrive more than once and out of order.

import { createTimbroPayments } from "@timbro/payments";

declare const rawBody: Uint8Array;
declare const signatureHeader: string;
declare function alreadyProcessed(eventId: string): Promise<boolean>;
declare function enqueueForRetrieval(eventId: string, eventType: string): Promise<void>;

async function handleWebhook(): Promise<Response> {
  const secretKey = process.env.TIMBRO_PAYMENTS_SECRET_KEY;
  const webhookSecret = process.env.TIMBRO_WEBHOOK_SECRET;
  if (!secretKey || !webhookSecret) return new Response("configuration error", { status: 500 });
  const timbro = createTimbroPayments({ secretKey });
  const event = timbro.webhooks.verify({ body: rawBody, signatureHeader, secret: webhookSecret });
  if (await alreadyProcessed(event.id)) return new Response(null, { status: 204 });
  await enqueueForRetrieval(event.id, event.type);
  return new Response(null, { status: 204 });
}

await handleWebhook();

Webhooks speed up notification, but authoritative inquiry resolves discrepancies. Classify errors by request validation, credential, provider, timeout, and fiscal status; retain context without storing card data.

Retrieve the Payment or FiscalDocument with a server-side credential after receiving the event. Retry only transient errors with backoff; operator_required needs intervention. Redact PAN, CVC, tokens, secrets, and sensitive parameters from logs and telemetry.