Webhooks, recuperación y errores

Verifica la firma con el secreto del ambiente, registra el identificador del evento y responde rápido. Procesa de forma idempotente: el mismo webhook puede llegar más de una vez y fuera de orden.

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();

Los webhooks aceleran la notificación, pero la consulta autoritativa resuelve una discrepancia. Clasifica errores por corrección del request, credencial, proveedor, timeout y estado fiscal; conserva el contexto sin guardar datos de tarjeta.

Consulta el Payment o FiscalDocument con una credencial server-side después de recibir el evento. Reintenta con backoff sólo los errores transitorios; un operator_required necesita intervención. Redacta PAN, CVC, tokens, secretos y parámetros sensibles de logs y telemetría.