Pular para o conteúdo
Esc
↑↓navegar↵abrir⌘Jpré-visualizar
Nesta página

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.

Esta página foi útil?