---
title: Webhooks
description: Entregas de eventos assinadas para o seu endpoint, com novas tentativas e um registro de entregas.
ai:
  exclude: true
---

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](/docs/pt-br/sdks) verificam as entregas com `verifyWebhook` (Node.js) e `verify_webhook` (Python).

```sh
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](/docs/pt-br/concepts/suppressions)), `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](/docs/pt-br/concepts/domains)). |
| `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](/docs/pt-br/receiving). `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](/docs/pt-br/concepts/unsubscribes) para o que significa `domain_id`.

### Eventos de caixas de entrada

As [caixas de entrada](/docs/pt-br/inboxes) 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.

```json title="email.failed"
{
  "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. |

```json title="email.suppressed"
{
  "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](https://www.standardwebhooks.com). 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}`.

```ts
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`.

```sh
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.

```ts
// 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.
