Webhooks

Registra un endpoint

Desde Settings → Webhooks, Agregar endpoint abre un diálogo que pide una URL y a cuáles de los diez tipos de evento suscribirte — ninguno viene marcado de entrada, el mismo criterio de mínimo privilegio con el que empiezan los permisos de una clave de API:

Al crearlo, el panel te muestra el secreto de firma una sola vez — la misma garantía que una clave de API: no queda guardado en ninguna columna, así que si lo pierdes, la única forma de volver a verlo es rotarlo, lo que también invalida el anterior. Cerrar sin copiarlo te pide confirmar, porque no hay forma de volver a esta pantalla después.

Cópialo en ese momento. Después, el panel lista el endpoint junto a cualquier otro que esta organización tenga registrado, señalado solo cuando algo necesita atención — con fallos o pausado, nunca una insignia de “activo” en uno saludable — con un menú para ver sus entregas, editar su URL o sus eventos, pausarlo o reanudarlo, o eliminarlo. Rotar el secreto vive un nivel más adentro, en la pantalla propia del endpoint, abierta desde su fila:

Verifica la firma

Cada entrega llega como un POST con este encabezado:

webhook-signature: v1=<firma en hexadecimal>

La firma es HMAC-SHA256(secreto, cuerpo), calculada sobre los bytes exactos del cuerpo — no sobre tu propia versión reserializada del JSON, que puede no coincidir byte a byte con lo que enviamos. Verifícala sobre el cuerpo crudo, antes de parsearlo:

import { createHmac, timingSafeEqual } from "node:crypto"

function isValidSignature(rawBody, header, secret) {
  const [scheme, signature] = header.split("=")
  if (scheme !== "v1" || signature === undefined) return false

  const expected = createHmac("sha256", secret).update(rawBody).digest("hex")

  return (
    expected.length === signature.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(signature))
  )
}

v1= es el esquema de la firma, no un separador cualquiera — dejamos espacio para introducir un segundo esquema en el futuro sin romper a quien ya está parseando este.

Compara con timingSafeEqual, nunca con ===. Una comparación normal de strings termina en el primer carácter que no coincide, y ese tiempo de respuesta es información: suficiente para que alguien reconstruya la firma correcta un carácter a la vez, probando contra tu propio endpoint.

Forma del payload

Toda entrega envía este mismo sobre, congelado en el momento en que el evento ocurrió — nunca recalculado después:

{
  "id": "01a0ba31-3fe4-7cc4-a1c6-64bdaaa5d99c",
  "type": "message.delivered",
  "createdAt": "2026-09-19T12:00:04Z",
  "data": {
    "messageId": "01a0ba31-4a15-7c9a-9b3d-3f1e6c2b7a44",
    "address": "ana@example.com",
    "status": "sent",
    "deliveryStatus": "delivered",
    "occurredAt": "2026-09-19T12:00:03Z",
    "bounceType": "Permanent"
  }
}

El contenido del mensaje y el id interno del proveedor nunca viajan en el payload: ninguno de los dos es algo que le corresponda a un endpoint que puede estar mal configurado.

Los diez tipos

status y deliveryStatus son los mismos campos que devuelve GET /v1/email/:messageId — un webhook es la otra forma de conocer los mismos dos valores, sin tener que consultar.

deliveryStatus es una escalera que nunca retrocede. Una queja que llega días después de una entrega gana igual, sin importar que su propio evento sea más tarde — por eso un message.complained puede llegar después de un message.delivered para el mismo mensaje, y es lo correcto.