Webhooks
Entregas de eventos assinadas para o seu endpoint, com novas tentativas e um registro de entregas.
Um webhook envia um POST HTTP para o seu endpoint cada vez que algo acontece: um e-mail é entregue, um contato se descadastra, chega um e-mail. Adicione endpoints no painel, em Webhooks, ou com POST /webhooks, e escolha quais eventos cada um recebe. Os SDKs verificam as entregas com verifyWebhook (Node.js) e 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"]
}'
A resposta traz o signing_secret (whsec_...). GET /webhooks/{id} o devolve de novo, e as linhas da listagem nunca o incluem.
Eventos
Eventos de e-mail
| Evento | Disparado quando |
|---|---|
email.scheduled |
Um e-mail foi aceito com um scheduled_at no futuro. |
email.sent |
O e-mail foi entregue ao serviço de envio. |
email.delivered |
O servidor do destinatário o aceitou. |
email.delivery_delayed |
A entrega está sendo retentada (caixa cheia, greylisting). |
email.bounced |
O e-mail deu bounce. data.bounce.type é Permanent (bounce permanente: o endereço também é suprimido), Transient ou Undetermined (não suprimido). |
email.complained |
O destinatário o marcou como spam. O endereço também é suprimido. |
email.failed |
O e-mail nunca será enviado. data.failed.reason diz por quê. |
email.suppressed |
O e-mail foi interrompido antes do envio. data.suppressed.reason diz por quê. |
email.opened |
Uma pessoa o abriu (exige rastreamento de abertura no domínio). |
email.clicked |
Uma pessoa clicou em um link rastreado (exige rastreamento de cliques). |
email.prefetched |
Uma máquina, e não uma pessoa, carregou o pixel de rastreamento ou seguiu um link (proxies de privacidade, scanners de segurança). Opt-in, veja abaixo. |
email.received |
Uma mensagem chegou a um dos seus domínios de recebimento. data.email_id é lido com GET /emails/receiving/{id}. |
email.prefetched é opt-in, como todo evento inbox.*: um endpoint o recebe só quando cita o evento, nunca por “todos os eventos”.
Eventos da conta
Eles não carregam e-mail. data descreve a situação da sua equipe.
| Evento | Disparado quando |
|---|---|
deliverability.warning |
Sua taxa de bounces permanentes ou de reclamações passou da linha de aviso. |
deliverability.paused |
A taxa passou da linha de pausa, e novos envios são recusados até ela se recuperar. |
quota.warning |
80% da sua cota foi usada (o limite do dia no Free, o volume incluído do período de cobrança nos planos pagos). |
quota.reached |
A cota acabou. |
quota.paused |
Só no Free: os envios ficam retidos até a meia-noite UTC ou até você fazer upgrade. |
Eventos de público
Eles disparam sempre que um contato ou a lista de supressão muda, seja quem for que mudou. data traz o contato (id, email, first_name, last_name, unsubscribed, created_at, updated_at) e uma source: api, dashboard, hosted_page ou one_click.
| Evento | Disparado quando | data extra |
|---|---|---|
contact.created |
Um contato foi adicionado. | |
contact.updated |
Nome, propriedades ou o indicador de descadastro mudaram. | |
contact.deleted |
Um contato foi excluído. Depois de um apagamento, o email aparece como [erased], então use o id. |
|
contact.unsubscribed |
Um destinatário usou um link de descadastro, ou você definiu unsubscribed como true. |
domain_id, domain_name (ambos null para um descadastro da equipe inteira) |
contact.resubscribed |
Um descadastro foi desfeito. | domain_id, domain_name |
contact.topic_opt_in, contact.topic_opt_out |
A inscrição de um contato em um tópico mudou. | topic_id, topic_name |
suppression.added, suppression.removed |
Um endereço entrou ou saiu da lista de supressão. | id, email, origin, source, source_id, created_at |
Veja Descadastros para o que significa domain_id.
Eventos de caixas de entrada
As caixas de entrada enviam 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 (um envio agendado foi recusado; próprio do BillionSend, com o rascunho e error: { name, message }). Todos são opt-in.
data sempre tem source (api, dashboard ou system) e inbox_id. Os objetos de e-mail e de rascunho nunca levam o corpo: busque-o pela API.
Para limitar um endpoint a algumas caixas, envie inbox_ids (até 100 caixas da sua equipe; null significa todas as caixas, uma lista vazia nenhuma). No painel, é Só estas caixas.
Payloads
Todo evento de e-mail traz email_id, from, to, subject e created_at, mais tags quando você enviou o e-mail com tags.
{
"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": ["ada@example.org"],
"subject": "Your receipt",
"created_at": "2026-10-13T10:00:02.317Z",
"failed": { "reason": "domain_not_verified" }
}
}
failed.reason |
O que aconteceu |
|---|---|
domain_not_verified |
O domínio de envio não estava verificado quando o e-mail saiu. |
domain_deleted |
O domínio de envio foi excluído enquanto o e-mail esperava. |
held_for_review_expired |
O e-mail ficou retido para uma verificação de segurança e não foi liberado em 7 dias. |
team_suspended |
A equipe foi suspensa e não foi reativada em 7 dias depois que o e-mail ficou retido. |
broadcasts_paused |
As transmissões da equipe foram pausadas e não foram retomadas em 7 dias depois que o e-mail ficou retido. |
ses_tenant_paused |
O SES pausou o envio da equipe e não retirou a pausa em 7 dias. |
body_missing, body_unreadable |
O conteúdo guardado estava ausente ou não pôde ser lido, por exemplo porque o e-mail ainda estava retido quando o conteúdo passou do período de retenção. |
message_rejected |
O serviço de envio recusou a mensagem, por exemplo porque ela tinha um vírus. |
retries_exhausted |
Todas as tentativas de envio falharam por erro temporário. |
send_interrupted |
Um envio foi cortado antes de ser confirmado, então o e-mail pode ou não ter saído. Não é tentado de novo. |
provider_error |
Qualquer outro erro que interrompeu o envio. |
{
"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": ["ada@example.org"],
"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 |
O endereço está na sua lista de supressão. |
contact_unsubscribed |
O contato está descadastrado na equipe inteira. |
domain_unsubscribed |
O destinatário se descadastrou deste domínio de envio. |
topic_unsubscribed |
O destinatário saiu do tópico do e-mail. |
contact_missing, contact_recipient_mismatch |
O contato foi excluído, ou o endereço dele mudou, antes de o e-mail sair. |
broadcast_missing, topic_missing |
A transmissão ou o tópico foi excluído antes de o e-mail sair. |
ineligible |
Qualquer outro motivo pelo qual o e-mail deixou de ser elegível. |
Se só alguns destinatários forem descartados, o e-mail vai para os demais e nenhum email.suppressed dispara. Cancelar uma transmissão não dispara nada para os e-mails que ela interrompe.
Verificar a assinatura
As entregas seguem o esquema Standard Webhooks. Cada requisição traz:
webhook-id: <message id>
webhook-timestamp: <unix seconds>
webhook-signature: v1,<base64 HMAC-SHA256>
Os mesmos valores também são enviados como svix-id, svix-timestamp e svix-signature, então um tratador escrito para qualquer uma das famílias de cabeçalhos funciona sem mudanças. O conteúdo assinado é {webhook-id}.{webhook-timestamp}.{corpo bruto}.
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"],
});
Verifique sempre contra o corpo bruto da requisição e rejeite timestamps antigos.
Segredos
Traga o seu. POST /webhooks aceita signing_secret: whsec_ seguido de base64 de 24 a 64 bytes. Envie o segredo que o seu receptor já usa e o endpoint continua funcionando sem novo deploy. Qualquer outra coisa retorna 422.
Rotacione. POST /webhooks/{id}/rotate, ou Rotacionar segredo no painel, cria um segredo novo (ou usa o de signing_secret) e o devolve. Durante overlap_hours (padrão 24, até 72) o segredo antigo continua assinando também, então cada entrega leva duas assinaturas e um receptor com qualquer um dos segredos a verifica. Troque o seu receptor em qualquer ponto da janela. 0 descarta o segredo antigo na hora, que é o que você quer para um segredo vazado. GET /webhooks/{id} mostra o fim da janela em 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 e novas tentativas
Responda com qualquer status 2xx e a entrega conta como bem-sucedida. Cada endpoint tem a própria fila, que envia até 50 requisições por segundo.
Uma tentativa que falha (não 2xx, timeout, erro de conexão) é repetida após 5 segundos, 5 minutos, 30 minutos, 2 horas, 5 horas e 10 horas: seis tentativas em cerca de 18 horas. Um 429 com cabeçalho Retry-After é respeitado (até uma hora) e não conta como tentativa. Um evento ainda não entregue 24 horas depois de entrar na fila é descartado.
Depois de 20 entregas falhas seguidas, o endpoint é desativado automaticamente (status auto_disabled) e não recebe nada até você ativá-lo de novo. Os eventos ocorridos nesse meio-tempo não são reenviados. Os proprietários da equipe recebem um e-mail quando as entregas começam a falhar, quando um endpoint é desativado e, no máximo uma vez por dia, quando a fila dele tem mais de seis horas de atraso.
A entrega é pelo menos uma vez, e os eventos não são entregues em ordem. O mesmo evento pode chegar mais de uma vez, e os eventos podem chegar em uma ordem diferente daquela em que aconteceram: um email.delivered pode chegar antes do email.sent do mesmo e-mail. Torne o seu tratador idempotente, usando webhook-id como chave, e ordene os eventos de um e-mail pelo created_at do payload (quando o evento aconteceu), nunca pela ordem de chegada. Uma exceção: email.failed com o motivo send_interrupted é uma suposição, e um email.sent, email.delivered ou outro resultado do mesmo e-mail o substitui mesmo quando o seu created_at é anterior.
// event: o payload verificado; webhookId: o cabeçalho webhook-id.
if (await alreadyHandled(webhookId)) return; // uma entrega repetida
const at = new Date(event.created_at);
const known = await db.emailStatus(event.data.email_id); // { status, at, guess } ou 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
Abra um endpoint no painel para ver cada entrega: o evento, o payload, a sua resposta e cada tentativa, guardados por 30 dias. Você pode apertar Tentar agora em uma entrega e Enviar evento de teste para experimentar o endpoint. A página também mostra o tamanho da fila do endpoint e há quanto tempo a entrega mais antiga espera.
Limites
| Free | Starter, Pro, Scale | |
|---|---|---|
| Endpoints de webhook por equipe | 1 | Sem limite |
Acima do limite, POST /webhooks retorna 403 plan_limit_reached. Depois de um downgrade, os endpoints existentes continuam funcionando, mas você não pode adicionar mais. Assine cada endpoint só nos eventos de que ele precisa: um endpoint em “todos os eventos” recebe um contact.created para cada contato que você importa.