Webhooks
Entregas de eventos firmadas a tu endpoint, con reintentos y un registro de entregas.
Un webhook envía un POST HTTP a tu endpoint cada vez que ocurre algo: se entrega un email, un contacto se da de baja, llega correo. Añade endpoints en el panel, en Webhooks, o con POST /webhooks, y elige qué eventos recibe cada uno. Los SDK verifican las entregas con verifyWebhook (Node.js) y verify_webhook (Python).
curl -X POST "https://api.billionsend.com/webhooks" \
-H "Authorization: Bearer bs_..." \
-H "Content-Type: application/json" \
-d '{
"endpoint": "https://example.com/webhooks/email",
"events": ["email.delivered", "email.bounced"]
}'
La respuesta incluye el signing_secret (whsec_...). GET /webhooks/{id} lo devuelve de nuevo, y las filas de las listas nunca lo incluyen.
Eventos
Eventos de email
| Evento | Se dispara cuando |
|---|---|
email.scheduled |
Se aceptó un email con un scheduled_at en el futuro. |
email.sent |
El email se entregó al servicio de correo. |
email.delivered |
El servidor del destinatario lo aceptó. |
email.delivery_delayed |
La entrega se está reintentando (buzón lleno, greylisting). |
email.bounced |
El email rebotó. data.bounce.type es Permanent (un rebote duro: la dirección también se suprime), Transient o Undetermined (no se suprime). |
email.complained |
El destinatario lo marcó como spam. La dirección también se suprime. |
email.failed |
El email nunca se enviará. data.failed.reason indica el motivo. |
email.suppressed |
El email se detuvo antes de enviarse. data.suppressed.reason indica el motivo. |
email.opened |
Una persona lo abrió (requiere el seguimiento de aperturas en el dominio). |
email.clicked |
Una persona hizo clic en un enlace rastreado (requiere el seguimiento de clics). |
email.prefetched |
Una máquina, no una persona, cargó el píxel de rastreo o siguió un enlace (proxies de privacidad, escáneres de seguridad). Es opcional; consulta más abajo. |
email.received |
Un mensaje llegó a uno de tus dominios de recepción. data.email_id se lee con GET /emails/receiving/{id}. |
email.prefetched es opcional, como todos los eventos inbox.*: un endpoint lo recibe solo cuando nombra el evento, nunca a través de «todos los eventos».
Eventos de la cuenta
Estos no llevan ningún email. data describe la situación de tu equipo.
| Evento | Se dispara cuando |
|---|---|
deliverability.warning |
Tu tasa de rebotes duros o de quejas superó el umbral de aviso. |
deliverability.paused |
La tasa superó el umbral de pausa, y los envíos nuevos se rechazan hasta que se recupere. |
quota.warning |
Se ha usado el 80 % de tu cuota (el límite de hoy en Free, el volumen incluido del periodo de facturación en los planes de pago). |
quota.reached |
La cuota se ha agotado. |
quota.paused |
Solo en Free: los envíos quedan retenidos hasta medianoche UTC o hasta que mejores de plan. |
Eventos de audiencia
Se disparan siempre que cambia un contacto o la lista de supresión, quien sea que lo cambie. data contiene el contacto (id, email, first_name, last_name, unsubscribed, created_at, updated_at) y un source: api, dashboard, hosted_page o one_click.
| Evento | Se dispara cuando | data adicional |
|---|---|---|
contact.created |
Se añadió un contacto. | |
contact.updated |
Cambió el nombre, las propiedades o la marca de baja. | |
contact.deleted |
Se eliminó un contacto. Tras un borrado, el email vale [erased], así que identifica por id. |
|
contact.unsubscribed |
Un destinatario usó un enlace de baja, o pusiste unsubscribed en true. |
domain_id, domain_name (ambos null en una baja de todo el equipo) |
contact.resubscribed |
Se retiró una baja. | domain_id, domain_name |
contact.topic_opt_in, contact.topic_opt_out |
Cambió la suscripción de un contacto a un tema. | topic_id, topic_name |
suppression.added, suppression.removed |
Una dirección entró o salió de la lista de supresión. | id, email, origin, source, source_id, created_at |
Consulta Bajas para saber qué significa domain_id.
Eventos de las bandejas de entrada
Las bandejas de entrada envían inbox.created, inbox.updated, inbox.deleted, inbox.expired, inbox.thread.created, inbox.thread.folder.updated, inbox.thread.labels.updated, inbox.email.received, inbox.email.sent, inbox.email.quarantined, inbox.draft.created, inbox.draft.updated, inbox.draft.sent, inbox.draft.deleted e inbox.draft.send_failed (se rechazó un envío programado; propio de BillionSend, con el borrador y error: { name, message }). Todos son opcionales.
data siempre incluye source (api, dashboard o system) e inbox_id. Los objetos de email y de borrador nunca llevan el cuerpo: obtenlo con la API.
Para limitar un endpoint a algunas bandejas de entrada, envía inbox_ids (hasta 100 bandejas de tu equipo; null significa todas las bandejas, una lista vacía ninguna). En el panel es Solo estas bandejas de entrada.
Cargas
Todo evento de email lleva email_id, from, to, subject y created_at, además de tags cuando enviaste el email con etiquetas.
{
"type": "email.failed",
"created_at": "2026-10-13T10:00:02.317Z",
"data": {
"email_id": "3f7b2c71-5274-4246-82f3-57bc1563c276",
"from": "Acme <billing@example.com>",
"to": ["success@simulator.amazonses.com"],
"subject": "Your receipt",
"created_at": "2026-10-13T10:00:02.317Z",
"failed": { "reason": "domain_not_verified" }
}
}
failed.reason |
Qué ocurrió |
|---|---|
domain_not_verified |
El dominio de envío no estaba verificado cuando salió el email. |
domain_deleted |
Se eliminó el dominio de envío mientras el email esperaba. |
held_for_review_expired |
El email quedó retenido por una comprobación de seguridad y no se liberó en 7 días. |
team_suspended |
El equipo fue suspendido y no se reactivó en los 7 días siguientes a la retención del email. |
broadcasts_paused |
Los envíos masivos del equipo se pausaron y no se reanudaron en los 7 días siguientes a la retención del email. |
ses_tenant_paused |
SES pausó el envío del equipo y no levantó la pausa en 7 días. |
body_missing, body_unreadable |
El contenido guardado faltaba o no se pudo leer, por ejemplo porque el email seguía retenido cuando su contenido superó el periodo de conservación. |
message_rejected |
El servicio de correo rechazó el mensaje, por ejemplo porque llevaba un virus. |
retries_exhausted |
Todos los intentos de envío fallaron por un error temporal. |
send_interrupted |
Un envío se cortó antes de confirmarse, así que el email puede haber salido o no. No se vuelve a intentar. |
provider_error |
Cualquier otro error que detuvo el envío. |
{
"type": "email.suppressed",
"created_at": "2026-10-14T09:30:00.912Z",
"data": {
"email_id": "b10f77bb-a99a-48c9-bd0a-a5d2cb1ba4a1",
"from": "Acme <hello@example.com>",
"to": ["success@simulator.amazonses.com"],
"subject": "Your trial ends tomorrow",
"created_at": "2026-10-14T09:30:00.912Z",
"suppressed": {
"type": "OnAccountSuppressionList",
"message": "The recipient is on your suppression list.",
"reason": "recipient_suppressed"
}
}
}
suppressed.reason |
Significado |
|---|---|
recipient_suppressed |
La dirección está en tu lista de supresión. |
contact_unsubscribed |
El contacto está dado de baja en todo el equipo. |
domain_unsubscribed |
El destinatario se dio de baja de este dominio de envío. |
topic_unsubscribed |
El destinatario se excluyó del tema del email. |
contact_missing, contact_recipient_mismatch |
El contacto se eliminó, o su dirección cambió, antes de que saliera el email. |
broadcast_missing, topic_missing |
El envío masivo o el tema se eliminó antes de que saliera el email. |
ineligible |
Cualquier otro motivo por el que el email dejó de ser apto. |
Si solo se descartan algunos destinatarios, el email va al resto y no se dispara ningún email.suppressed. Cancelar un envío masivo no dispara nada por los emails que detiene.
Verifica la firma
Las entregas siguen el esquema Standard Webhooks. Cada solicitud lleva:
webhook-id: <message id>
webhook-timestamp: <unix seconds>
webhook-signature: v1,<base64 HMAC-SHA256>
Los mismos valores se envían también como svix-id, svix-timestamp y svix-signature, así que un manejador escrito para cualquiera de las dos familias de cabeceras funciona sin cambios. El contenido firmado es {webhook-id}.{webhook-timestamp}.{raw body}.
import { Webhook } from "standardwebhooks";
const wh = new Webhook("whsec_...");
const event = wh.verify(rawBody, {
"webhook-id": req.headers["webhook-id"],
"webhook-timestamp": req.headers["webhook-timestamp"],
"webhook-signature": req.headers["webhook-signature"],
});
Verifica siempre contra el cuerpo sin procesar de la solicitud y rechaza las marcas de tiempo antiguas.
Secretos
Trae el tuyo. POST /webhooks acepta signing_secret: whsec_ seguido de base64 de entre 24 y 64 bytes. Pasa el secreto que tu receptor ya usa y el endpoint sigue funcionando sin volver a desplegar. Cualquier otra cosa devuelve 422.
Rota. POST /webhooks/{id}/rotate, o Rotar secreto en el panel, crea un secreto nuevo (o toma el de signing_secret) y lo devuelve. Durante overlap_hours (24 por defecto, hasta 72) el secreto antiguo sigue firmando también, así que cada entrega lleva dos firmas y un receptor con cualquiera de los dos secretos la verifica. Cambia tu receptor en cualquier momento de la ventana. 0 descarta el secreto antiguo al instante, que es lo que quieres para uno filtrado. GET /webhooks/{id} muestra cuándo termina la ventana como previous_secret_expires_at.
curl -X POST "https://api.billionsend.com/webhooks/$WEBHOOK_ID/rotate" \
-H "Authorization: Bearer bs_..." \
-H "Content-Type: application/json" \
-d '{ "overlap_hours": 24 }'
Entrega y reintentos
Responde con cualquier estado 2xx y la entrega cuenta como correcta. Cada endpoint tiene su propia cola, que envía hasta 50 solicitudes por segundo.
Un intento fallido (no 2xx, tiempo de espera agotado, error de conexión) se reintenta a los 5 segundos, 5 minutos, 30 minutos, 2 horas y 5 horas. Son seis intentos en total, a lo largo de unas 7 horas y 35 minutos, y una entrega que falla el sexto se abandona. Un 429 con una cabecera Retry-After se respeta (hasta una hora) y no cuenta como intento. Un evento que sigue sin entregarse 24 horas después de ponerse en cola se descarta.
Tras 20 entregas seguidas que fallaron todos sus intentos, el endpoint se desactiva automáticamente (estado auto_disabled) y no recibe nada hasta que lo actives de nuevo. Los eventos ocurridos entretanto no se reproducen. Los propietarios del equipo reciben un email cuando las entregas empiezan a fallar, cuando se desactiva un endpoint y, como máximo una vez al día, cuando su cola acumulada tiene más de seis horas.
La entrega es al menos una vez, y los eventos no se entregan en orden. El mismo evento puede llegar más de una vez, y los eventos pueden llegar en un orden distinto al que ocurrieron: un email.delivered puede llegar antes que el email.sent del mismo email. Haz tu manejador idempotente, usando webhook-id como clave, y ordena los eventos de un email por el created_at de la carga (cuándo ocurrió el evento), nunca por la llegada. Una excepción: email.failed con el motivo send_interrupted es una suposición, y un email.sent, email.delivered u otro resultado del mismo email la sustituye aunque su created_at sea anterior.
// event: the verified payload; webhookId: the webhook-id header.
if (await alreadyHandled(webhookId)) return; // a repeat delivery
const at = new Date(event.created_at);
const known = await db.emailStatus(event.data.email_id); // { status, at, guess } or null
const newer = !known || at > known.at || known.guess;
if (newer) {
const guess = event.type === "email.failed" && event.data.failed.reason === "send_interrupted";
await db.setEmailStatus(event.data.email_id, { status: event.type, at, guess });
}
await markHandled(webhookId);
Registro de entregas
Abre un endpoint en el panel para ver cada entrega: el evento, la carga, tu respuesta y cada intento, conservados 30 días. Puedes pulsar Reintentar ahora en una entrega, y Enviar evento de prueba para probar el endpoint. La página muestra también el tamaño de la cola del endpoint y cuánto lleva esperando su entrega más antigua.
Límites
| Free | Starter, Pro, Scale | |
|---|---|---|
| Endpoints de webhook por equipo | 1 | Sin límite |
Al pasar el límite, POST /webhooks devuelve 403 plan_limit_reached. Tras bajar de plan, los endpoints existentes siguen funcionando pero no puedes añadir más. Suscribe cada endpoint solo a los eventos que necesita: un endpoint con «todos los eventos» recibe un contact.created por cada contacto que importas.