¿Cómo funcionan los webhooks de Resend?

El flujo de trabajo de los webhooks de Resend

El flujo empieza cuando usted crea un endpoint HTTPS público y lo registra en Resend con los tipos de evento que necesita su aplicación. Cuando se produce un evento coincidente, Resend envía una solicitud POST con un payload JSON. El payload incluye un tipo, como email.sent, email.delivered, email.bounced o email.complained, una fecha de creación y datos específicos del evento. Enrute el procesamiento según el campo type en lugar de suponer que todos los payloads tienen la misma forma.

Verifique la solicitud antes de procesarla

Lea la solicitud como texto sin procesar y verifíquela con el secreto de firma del webhook y los encabezados svix-id, svix-timestamp y svix-signature. Hágalo antes de analizar el payload o actuar en consecuencia. Analizar el JSON y volver a serializarlo puede cambiar los bytes y hacer que una firma legítima falle. Rechace las solicitudes que no superen la verificación y guarde el secreto de firma en un gestor de secretos o en una variable de entorno protegida, no en el código fuente.

Haga que la gestión de eventos sea idempotente

Resend documenta una entrega de tipo «al menos una vez», por lo que el mismo evento puede llegar a su endpoint más de una vez. Guarde el svix-id con una restricción de unicidad y omita la lógica de negocio cuando ese identificador ya se haya procesado. Tampoco dependa del orden de llegada, porque los reintentos y los retrasos de red pueden desordenar los eventos. Use el valor created_at del evento cuando el orden importe y modele los cambios de estado para que un evento antiguo no pueda sobrescribir por accidente un estado más reciente.

Confirme rápido y procese de forma segura

Devuelva HTTP 200 una vez que el evento se haya verificado y registrado de forma duradera, y realice después el trabajo más lento mediante una cola o un worker en segundo plano. Un tiempo de espera agotado o una respuesta no satisfactoria provocan un nuevo intento de entrega, así que los manejadores síncronos largos generan duplicados evitables. Separe la ingesta de los efectos secundarios, como actualizar un registro de supresión, avisar a soporte o registrar un rebote. Cada efecto secundario también debe poder repetirse sin riesgo o estar protegido por el identificador de evento almacenado.

Pruebe los reintentos, las repeticiones y la recuperación ante fallos

Pruebe el endpoint con tipos de evento representativos antes de pasar a producción, incluidas firmas no válidas, identificadores duplicados, marcas de tiempo desordenadas y fallos temporales de la base de datos. Resend reintenta las entregas fallidas siguiendo un calendario de backoff y le permite repetir tanto los mensajes de webhook fallidos como los correctos. Use la repetición para recuperarse tras una interrupción o para validar código actualizado del manejador, pero mantenga activa la deduplicación para que la recuperación no repita efectos secundarios visibles para los clientes.

Preguntas habituales de los equipos

Fuentes primarias

• Gestión de webhooks — Resend
• Verificar solicitudes de webhooks — Resend
• Reintentos y repeticiones — Resend
• Tipos de eventos de webhook — Resend