Saltar al contenido
Esc
↑↓navegar↵abrir⌘Jvista previa
En esta página

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.

¿Te ha resultado útil esta página?