¿Qué es un webhook?

Cuando Bird llama a tu endpoint, el receptor debe preservar el evento antes de comenzar el trabajo. Un webhook es una solicitud HTTP que un sistema envía a tu aplicación cuando algo sucede. El emisor firma el POST hacia tu URL registrada. Tu receptor decide cuándo el evento se acepta de forma durable.

¿En qué se diferencia un webhook de hacer polling a una API?

Polling significa que tu aplicación llama a una API en un horario fijo y comprueba si hay cambios. Un webhook invierte esa dirección: el proveedor llama a tu endpoint cuando ocurre un evento, así evitas solicitudes innecesarias y reaccionas antes.

Los webhooks necesitan un endpoint HTTPS público que pueda recibir solicitudes mientras se entregan eventos. El polling funciona desde cualquier lugar y permite a tu aplicación elegir cuándo consultar el estado. Usa webhooks para notificaciones oportunas. Usa la API para obtener más detalle del recurso cuando un evento solo lleva identificadores.

¿Cómo es una solicitud de webhook?

Una solicitud de webhook es un HTTP POST con encabezados y un sobre de evento JSON. El evento de entrega de correo de Bird tiene type, un timestamp de evento y data específicos del tipo:

{
  "type": "email.delivered",
  "timestamp": "2026-06-10T14:30:00Z",
  "data": {
    "email_id": "em_01krdgeqcxet5s7t44vh8rt9mg",
    "recipient_id": "er_01krdgeqcxet5s7t44vh8rt9mg",
    "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
    "recipient": "user@example.com",
    "recipient_role": "to",
    "tags": [{ "name": "category", "value": "welcome" }],
    "metadata": { "order_id": "ord_123" },
    "broadcast_id": null
  }
}

El ID del mensaje es data.email_id. La identidad de la entrega es el encabezado webhook-id, que permanece igual cuando Bird reintenta o reproduce ese evento. El timestamp del cuerpo registra cuándo ocurrió el evento. El encabezado webhook-timestamp registra este intento de entrega, así que las dos marcas de tiempo responden preguntas distintas. Consulta los campos de eventos de correo para los payloads específicos de cada evento.

¿Cómo verificas la firma de un webhook?

Conserva los bytes crudos de la solicitud y verifica la firma antes de parsear o almacenar el evento. Bird SDK comprueba los encabezados webhook-id, webhook-timestamp y webhook-signature. Aplica la tolerancia de timestamp por ti. Usa la guía de firma en lugar de escribir un segundo verificador.

Si necesitas entender la entrada de firma, Bird usa {webhook-id}.{webhook-timestamp}.{raw request body}. El secreto del endpoint comienza con whsec_; elimina ese prefijo y decodifica en base64 el resto antes de calcular HMAC-SHA256. Durante la rotación de secretos, el encabezado de firma puede contener varios valores v1, separados por espacios, así que acepta un valor coincidente de los secretos activos.

Rechaza las solicitudes malformadas, no autenticadas o caducadas antes de almacenarlas. Parsear JSON primero puede cambiar espacios en blanco u orden de claves, y hace que los bytes ya no coincidan con el mensaje firmado.

¿Cómo debes almacenar y confirmar un webhook?

Persiste un evento verificado y su trabajo durable antes de devolver éxito. Inserta el evento con clave webhook-id. Inserta el elemento de trabajo para un evento nuevo. Confirma ambos en una transacción o un diseño equivalente de inbox y outbox durables.

read raw bytes and headers
verify the signature and timestamp with the Bird SDK
begin a durable transaction
  insert the inbox event keyed by webhook-id, unless it already exists
  insert a durable work item for a new event
commit the transaction
return 204
worker processes the persisted event idempotently

Un duplicado que ya está almacenado de forma durable puede recibir 204 sin generar más trabajo. Devuelve un código distinto de 2xx cuando falla la confirmación durable, para que Bird reintente la entrega. Una vez que devuelves éxito, reintenta el worker local desde tu registro durable en lugar de esperar que Bird envíe el evento de nuevo.

Este orden es un diseño de aplicación para la semántica de entrega al menos una vez de Bird. No es una cola que Bird ejecuta por ti. La guía de duplicados e idempotencia cubre la decisión de deduplicación con más detalle.

¿Cómo funcionan los reintentos y la reproducción de webhooks?

Bird da a una entrega normal 15 segundos para recibir una respuesta. Cualquier estado 2xx se considera exitoso. Un estado distinto de 2xx, una redirección o un timeout falla y sigue el calendario de reintentos.

La curva tiene 8 intentos incluyendo la solicitud inicial. Cada retraso se aplica con un jitter de más o menos 20 %. Un 429 o timeout de conexión eleva el retraso base a 60 segundos. Un valor Retry-After positivo se limita entre ese base y el doble del base antes del jitter, así que la tabla describe retrasos base, no tiempos de llegada exactos. Consulta cómo se reintentan los webhooks fallidos para la ruta de fallo.

Las entregas no tienen orden garantizado, así que no actualices el estado actual de la aplicación solo a partir del orden de llegada. Usa el timestamp del evento y el estado de tu recurso cuando los eventos puedan llegar desordenados.

Cuando se pierde una entrega, inspecciona los intentos de webhook. Corrige el receptor. Crea una reproducción de webhook. Bird omite las entregas que el endpoint ya recibió con éxito. Una reproducción reutiliza el webhook-id original, así que la misma clave de deduplicación la protege.

¿Qué debes conectar después de aprender los fundamentos de webhooks?

Crea un endpoint. Verifica y acepta de forma durable sus entregas firmadas. Inspecciona los intentos de entrega. Reproduce eventos perdidos. Luego usa la rotación de secretos para desplegar un nuevo secreto de firma sin perder entregas.