Webhooks

Receba eventos de mensagem, status e saúde da WABA por HTTP: a BotoZap faz POST no seu endpoint e assina cada corpo para você validar a origem.

Webhooks entregam a você tudo que chega das WABAs dos seus clientes: mensagens recebidas, atualizações de status, saúde da WABA e outros eventos. Você registra uma URL, a BotoZap faz POST nela e você responde 2xx para confirmar. A lista completa de eventos, com categoria, chave de idempotência e payload de cada um, está no Catálogo de eventos.

Intenção manual e saúde automática

Um endpoint tem duas dimensões independentes. active é a sua intenção manual: true significa que você quer o endpoint habilitado e false desativa novas entregas. health_status é o veredito automático da plataforma e pode ser unverified, healthy, degraded ou paused; ele não substitui nem altera active.

Todo endpoint novo nasce com health_status=unverified. Mesmo que o cadastro use active=true, a BotoZap não admite nem enfileira eventos reais antes de POST /api/v1/webhooks/{id}/testretornar 2xx. Um teste 2xx verifica a configuração e ativa o endpoint; uma falha de teste retorna 502, preserva o estado anterior e não incrementa failure_streak nem os alertas.

activehealth_statusEventos reaisEntregas
falsequalquer valornão são admitidosas já aceitas ficam retidas
trueunverifiednão são admitidosaguardam um teste 2xx
truehealthy ou degradedsão admitidostentadas conforme o retry
truepausedsão retidos por até 14 diasnão há POST até novo teste 2xx

A saúde é acompanhada por canal (cada número do WhatsApp e cada conta do Instagram): um canal pode pausar enquanto os outros continuam entregando. O health_status do endpoint é o resumo dos canais e channels_health mostra cada canal com falha (veja Degradação automática).

Como funciona

Quando um evento acontece, a BotoZap faz um POST no seu endpoint HTTPS com o corpo em JSON. A conexão só sai para destinos públicos (URLs de loopback, IP privado ou não-resolvível são recusadas no cadastro). Cada requisição leva três headers úteis:

  • X-Webhook-Event: o tipo do evento, ex. whatsapp.message.received.
  • X-Idempotency-Key: chave estável do evento, o wamid para mensagens, wamid:status para atualizações de status e uma chave própria por transição nos eventos de CRM; nos eventos de conta, ela é derivada do payload normalizado. O formato de cada uma está no catálogo. Use para deduplicar reentregas.
  • X-Webhook-Signature: a assinatura HMAC do corpo (veja abaixo).

Se o seu endpoint exige autenticação, cadastre um header Authorization (ex. Bearer seu-token): no painel de Webhooks, pelo campo Cabeçalho Authorization (só Administrador), ou na API, por headers.Authorization. O valor vai igual, em cada entrega e no teste, e nunca é devolvido.

Responda rápido com 2xx, em até 10 segundos: é o único ACK que a BotoZap aceita. Fora disso (qualquer outro status, timeout ou erro de rede) a entrega é tratada como falha. A única exceção é o Web App do Google Apps Script, que responde todo POST com 302 para script.googleusercontent.com depois de já ter executado o doPost: a BotoZap aceita esse 302 como ACK, sem seguir o redirecionamento, e o registra como 200. Trate erros dentro do próprio script, porque o Google responde 302 mesmo quando ele falha. No caminho health-aware, o próximo POST segue a curva de 1 / 2 / 4 / 8 / 16 / 32 / 60 minutos (a última duração é repetida): não há teto fixo de seis tentativas. A exceção é um evento recusado sozinho, que esgota na tentativa 30 (veja Degradação automática). Por isso o mesmo evento pode chegar mais de uma vez: use o X-Idempotency-Key para tratar duplicatas, nunca um Set em memória, que não sobrevive a um restart ou a múltiplas réplicas (veja o receptor de exemplo abaixo). Detalhes completos em Confiabilidade e entrega.

Depois que o seu endpoint confirma uma entrega, a BotoZap manda até 10 eventos ao mesmo tempo para ele. O servidor precisa aceitar requisições simultâneas: se ele atende uma por vez, as outras estouram o tempo e voltam pela curva de tentativas. Enquanto o endpoint falha, a BotoZap volta a mandar um evento por vez.

Corpo de uma mensagem recebida

No evento whatsapp.message.received, o corpo do POST tem cinco campos:

  • event: sempre whatsapp.message.received.
  • customer_id: o Cliente dono do número que recebeu o evento; null quando a cadeia não pôde ser resolvida.
  • phone_number_id: o phone_number_id da Meta que recebeu a mensagem.
  • message: o objeto de mensagem cru da Cloud API (id, tipo, conteúdo e context quando é resposta ou botão). Quando o contato chega por um anúncio Click-to-WhatsApp, a mensagem traz o referral da Meta (source_id do anúncio, source_url, source_type, headline, ctwa_clid etc.; o ctwa_clid não vem em anúncios exibidos no Status).
  • contact: a identidade de quem enviou, com wa_id, user_id, username, phone, profile_name e metadata (os campos personalizados do contato).

Os eventos de status (enviado, entregue, lido, falhou) não trazem o objeto contact. Mensagens que a equipe envia pelo app WhatsApp Business num número em coexistência não chegam em messages: elas saem como whatsapp.message.echo (no mesmo formato deste corpo e com source app), e edições e remoções feitas no app como whatsapp.message.edited e whatsapp.message.revoked, só para Endpoints que assinam a categoria opt-in app_messages (veja coexistência no catálogo).

Os eventos de status trazem pricing e, quando a Meta manda, conversation. Desde a versão 24 da Graph API, conversation só aparece para mensagens enviadas dentro da janela grátis do Free Entry Point (anúncio Click-to-WhatsApp): pricing.type vem como free_entry_point, conversation.id identifica a janela e conversation.expiration_timestamp (só no sent) diz quando ela termina. O BotoZap grava esse fim em fep_expires_at da conversa (GET /api/v1/conversations).

Consentimento (categoria messages)

Cada mudança de Consentimento emite crm.contact.consent_changed. O nome começa com crm., mas a categoria de inscrição é messages — Endpoints assinados só em crm não o recebem. O corpo traz canal, Finalidade, estado, origem e evidência.

Eventos de CRM (categoria crm)

A categoria crm entrega todo evento crm.* exceto o de Consentimento: mudança de etapa do contato, crm.opportunity.created/updated, crm.demand.created/updated, crm.appointment_created e crm.appointment_updated. O payload de cada um está no catálogo; o mais usado é detalhado abaixo.

Quando um contato muda de etapa no funil — arrastado no kanban, via PATCH /api/v1/contacts/{id}, promovido automaticamente por uma resposta de transmissão ou porque a etapa foi excluída — a BotoZap emite crm.contact.stage_changed. O corpo traz:

  • event: sempre crm.contact.stage_changed.
  • customer_id: o Cliente dono da conta de canal do contato.
  • phone_number_id: o phone_number_id da Meta do número dono do contato. Só vem quando o canal do contato é o WhatsApp; nos demais canais o campo fica ausente e a origem é o channel_account.
  • contact: a identidade do contato (id, wa_id, phone, profile_name…).
  • previous_stage / new_stage: a etapa anterior e a nova, cada uma como { id, key, label }. Ausentes quando o contato entra no funil (sem anterior) ou sai dele (sem nova).
  • changed_by: manual (kanban/API), auto (transmissão/resposta) ou system (etapa limpa ou excluída).

Use este evento para reagir ao momento certo da negociação — ex.: contato entrou em "Fechou" → crie o agendamento, dispare a cobrança, acione seu agente. O mesmo evento sai no stream durável de GET /api/v1/events e na subscription MCP.

Saúde da WABA e conexão (categoria account)

A categoria account encaminha as mudanças de saúde que a Meta envia para a WABA e avisa quando um número termina de conectar. Ela é opt-in: endpoints que assinam apenas messages, statuses ou crm não recebem esses eventos. O payload é normalizado a partir dos campos que a BotoZap persiste para acompanhar a saúde; valores ausentes permanecem como null.

Atualização da conta

O evento whatsapp.account.updated corresponde ao field da Meta account_update:

{
  "event": "whatsapp.account.updated",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "waba_id": "4207187232868022",
  "account_event": "ACCOUNT_RESTRICTION",
  "ban_state": null,
  "restrictions": [
    {
      "restriction_type": "RESTRICTED_BIZ_INITIATED_MESSAGING",
      "expiration": "2026-08-31T00:00:00.000Z"
    }
  ],
  "occurred_at": "2026-08-27T12:00:00.000Z"
}
  • account_event e ban_state refletem, respectivamente, o evento e o estado de banimento conhecidos.
  • customer_id identifica o Cliente dono da WABA; em eventos sem número, a resolução usa o waba_id da conexão.
  • restrictions é a lista persistida de restrições, com restriction_type e expiration. Uma lista vazia significa que a Meta informou não haver restrições.
  • occurred_at é o horário do evento na Meta; pode ser null quando o payload não trouxer um horário legível.
  • violation_type só aparece quando a Meta reporta uma violação de política (account_event ACCOUNT_VIOLATION), por exemplo SPAM. Em geral o banimento (DISABLED_UPDATE) chega logo em seguida como um evento separado.
  • disconnection_reason e disconnection_initiated_by só aparecem em PARTNER_REMOVED de número em coexistência, quando a Meta informa por que desligou a conexão: por exemplo USER_RE_REGISTERED (o WhatsApp Business foi registrado em outro aparelho), CHANGE_NUMBER, BUSINESS_DOWNGRADE (o número foi para o WhatsApp comum), PRIMARY_INACTIVITY, COMPANION_INACTIVITY ou ACCOUNT_DISCONNECTED. disconnection_initiated_by é USER ou SYSTEM.

Exemplo de violação de política:

{
  "event": "whatsapp.account.updated",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "waba_id": "4207187232868022",
  "account_event": "ACCOUNT_VIOLATION",
  "ban_state": null,
  "restrictions": null,
  "violation_type": "SPAM",
  "occurred_at": "2026-09-03T16:21:30.000Z"
}

Atualização de limite do número

O evento whatsapp.phone_number.quality_updated corresponde ao field phone_number_quality_update. Apesar do nome legado do field, o payload atual informa o evento de limite e o tier de conversas; ele não é uma leitura de quality_rating. Ao receber esse field, o BotoZap relê os números da conexão na Graph e atualiza a qualidade e o status no painel na hora, sem esperar a sincronização diária.

{
  "event": "whatsapp.phone_number.quality_updated",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "waba_id": "4207187232868022",
  "phone_number_id": "1279498075235551",
  "display_phone_number": "+1 555-078-3881",
  "messaging_limit_tier": "TIER_2K",
  "occurred_at": "2026-08-27T12:00:00.000Z"
}
  • phone_number_id e display_phone_number identificam o número persistido na conexão da WABA.
  • customer_id identifica o Cliente dono do número.
  • messaging_limit_tier é o tier persistido para o número.
  • Sem número ou tier utilizável, a BotoZap não cria esse evento; occurred_at pode ser null quando ausente ou ilegível.

Número conectado

O evento whatsapp.phone_number.connected sai quando o Embedded Signup termina e o número fica conectado, pelo Link de conexão ou pelo painel, em conexão dedicada ou coexistência. É o jeito de saber que o cliente concluiu a conexão sem consultar GET /api/v1/customers/{id}/setup_links em loop.

{
  "event": "whatsapp.phone_number.connected",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "waba_id": "4207187232868022",
  "phone_number_id": "1279498075235551",
  "display_phone_number": "+55 11 3333-4444",
  "connection_mode": "coexistence",
  "setup_link_id": "5b2f7c1e-8a4d-4e3f-9b6a-1c2d3e4f5a60",
  "occurred_at": "2026-09-30T13:05:00.000Z"
}
  • connection_mode é dedicated (número só na API) ou coexistence (o número segue no app WhatsApp Business).
  • setup_link_id é o Link de conexão usado. A chave de idempotência é whatsapp.phone_number.connected:<setup_link_id>:<phone_number_id>: uma nova conexão do mesmo número por outro link gera outro evento; repetir o mesmo link, não.
  • Vale o filtro por Cliente do Endpoint e o evento também entra em GET /api/v1/events.
  • Conexão concluída sem número (a Meta ainda não informou nenhum) não gera o evento.
  • Não há evento de desconexão. Quando a Meta informa que o acesso acabou, chega whatsapp.account.updated com o account_event da Meta (por exemplo PARTNER_APP_UNINSTALLED ou PARTNER_REMOVED, este com disconnection_reason quando a Meta informa o motivo).
  • Número em coexistência (com o app WhatsApp Business no celular): quando o app é reinstalado ou muda de aparelho, a Meta tira o número da API e chega whatsapp.account.updated com account_event ACCOUNT_OFFBOARDED. Envios falham até o dono terminar o registro no app; aí chega ACCOUNT_RECONNECTED e o número volta sozinho, sem reconectar.

Registrar um webhook

Crie um endpoint com POST /api/v1/webhooks informando a url (obrigatoriamente https://) e a lista de events: aceita as categorias messages (mensagens recebidas), statuses (status de entrega/ leitura das que você enviou e término de Régua), crm (etapa do contato, oportunidades, demandas e agendamentos), account (saúde da WABA) e app_messages (o que a equipe envia, edita ou apaga pelo app em coexistência), não nomes finos de evento. Valores fora dessa lista são descartados; sem nenhum válido, a API responde 422 invalid_events. Endpoints existentes continuam recebendo só o que assinaram — crm, account e app_messages são opt-in; app_messages não chega nem a um Endpoint com events vazio. O campo opcional customer_id limita o endpoint aos eventos de um Cliente; omitido ou null, preserva o recebimento da Conta inteira. O campo opcional channel_account_ids limita o endpoint a alguns canais (veja Canais do webhook).

Testando com chave sandbox? Ela não cadastra webhooks pela API e recebe 403 sandbox_forbidden. Cadastre o endpoint pelo painel, em Webhooks: ele recebe os eventos simulados do sandbox com a mesma assinatura e as mesmas retentativas de produção.

Registrar um endpoint de webhook

Cria o endpoint com `health_status=unverified`: mesmo com `active=true`, eventos reais só são admitidos depois de um teste assinado com resposta 2xx.

curl https://botozap.com.br/api/v1/webhooks \
  -X POST \
  -H "X-API-Key: $BOTOZAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://exemplo-integracao.com.br/webhooks/botozap",
  "events": [
    "messages",
    "statuses"
  ],
  "customer_id": null,
  "channel_account_ids": null
}'

Resposta 201

{
  "data": {
    "id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
    "customer_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
    "channel_account_ids": null,
    "url": "https://exemplo-integracao.com.br/webhooks/botozap",
    "events": [
      "messages",
      "statuses"
    ],
    "active": true,
    "has_authorization": false,
    "health_status": "unverified",
    "failure_streak": 0,
    "verified_at": null,
    "last_success_at": null,
    "last_failure_at": null,
    "last_response_code": null,
    "next_attempt_at": null,
    "paused_at": null,
    "channels_health": [],
    "secret": "whsec_...",
    "created_at": "2026-07-14T12:00:00.000Z",
    "updated_at": "2026-07-14T12:00:00.000Z"
  }
}

O `secret` (`whsec_...`) só aparece nesta resposta de criação — guarde-o agora, ele assina cada entrega (`X-Webhook-Signature`).

`active` expressa sua intenção manual; `health_status` começa como `unverified`. Execute `POST /api/v1/webhooks/{id}/test` e receba 2xx para verificar e ativar o endpoint.

`customer_id` é opcional: omitido ou `null`, o endpoint recebe eventos de todos os Clientes da Conta; informado, recebe apenas eventos daquele Cliente. O id precisa pertencer à Conta da chave.

`channel_account_ids` é opcional: omitido ou `null`, o endpoint recebe eventos de todos os canais da Conta; uma lista de 1 a 100 ids (os mesmos de `GET /api/v1/channel_accounts` e do `channel_account.id` de cada payload) limita o endpoint a esses canais. Com `customer_id`, os canais precisam ser desse Cliente. Lista vazia, mais de 100 itens ou item que não é UUID responde `422 invalid_channel_account_ids`; canal de outra Conta (ou de outro Cliente) responde `404 channel_account_not_found` e nenhum endpoint é criado.

A URL precisa usar https:// e resolver para um destino público (o BotoZap bloqueia loopback/redes privadas por segurança).

`events` aceita `messages`, `statuses`, `crm`, `account` e `app_messages`. `app_messages` (o que a equipe envia, edita ou apaga pelo app em coexistência: `whatsapp.message.echo`, `.edited`, `.revoked`) é opt-in: só chega se estiver na lista.

O secret é opcional na criação: omitido, a BotoZap gera um whsec_…; informado, precisa ter de 16 a 256 caracteres (sem quebras de linha), senão a API responde 422 invalid_secret. Ele aparece somente na resposta 201 de criação. Guarde-o nesse momento: listagens, consultas e atualizações não devolvem essa credencial (para trocar, veja Rotacionar o secret). O endpoint também aceita GET/PATCH/DELETE /api/v1/webhooks/{id} para consultar, atualizar e remover, e POST /api/v1/webhooks/{id}/test para disparar um evento de teste.

Canais do webhook

channel_account_ids escolhe de quais canais o endpoint recebe eventos. Os ids são os mesmos de GET /api/v1/channel_accounts e do channel_account.id que vai em todo payload de webhook. Use para separar, por exemplo, o número de testes do número de produção em endpoints diferentes.

ValorNo POSTNo PATCH
ausentetodos os canais da Contanão muda
nulltodos os canais da Contavolta a receber de todos os canais
lista de 1 a 100 idssó esses canaistroca a lista inteira por esta

Com customer_id, os canais precisam ser desse Cliente. A troca de canais não mexe na saúde nem na verificação: não exige novo teste. Nas leituras, channel_account_ids vem null quando o endpoint recebe de todos os canais, ou a lista ordenada dos canais marcados. A lista pode ficar vazia: quando um canal marcado é excluído, ele sai da lista, mas o endpoint não volta a receber de todos os canais sozinho. Com a lista vazia, o endpoint não recebe evento nenhum até você marcar canais ou enviar null.

Como cada evento é filtrado num endpoint com canais escolhidos:

  • evento de um canal marcado é entregue; de um canal não marcado, não;
  • evento da WABA que não cita um número (por exemplo, status de template) é entregue se algum número marcado é daquela WABA;
  • evento sem canal identificável só vai para endpoints de todos os canais;
  • o webhook.test do teste manual nunca é filtrado.
ErroQuando
422 invalid_channel_account_idsO valor não é null nem lista, a lista está vazia, tem mais de 100 itens ou algum item não é um UUID.
404 channel_account_not_foundAlgum canal não existe nesta Conta ou, com customer_id, não é desse Cliente. No POST, nenhum endpoint é criado; no PATCH, nada é alterado.
422 channel_accounts_outside_customerO PATCH troca o customer_id de um endpoint com canais escolhidos sem enviar channel_account_ids, e algum canal marcado não é do novo Cliente. Envie a lista nova no mesmo pedido (ou null para todos os canais). Nada é alterado.

Verificar, ativar e corrigir

Execute o teste assinado depois de criar o endpoint e novamente sempre que corrigir o destino. Qualquer resposta HTTP entre 200 e 299 verifica a configuração, zera o streak de todos os canais, retoma os canais pausados e ativa o endpoint. Resposta não-2xx, timeout ou erro de conexão retorna 502 test_delivery_failed e não penaliza a saúde automática.

Testar e ativar um endpoint

Envia `webhook.test` assinado. Qualquer resposta HTTP 2xx verifica a configuração, zera o streak e ativa o endpoint para eventos reais.

curl https://botozap.com.br/api/v1/webhooks/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11/test \
  -X POST \
  -H "X-API-Key: $BOTOZAP_KEY"

Resposta 200

{
  "data": {
    "success": true,
    "response_code": 204,
    "health_status": "healthy",
    "active": true
  }
}

Se o destino responder fora de 2xx, ou houver timeout/erro de rede, a API retorna 502 `test_delivery_failed`; a falha manual não incrementa `failure_streak` nem cruza alertas.

Depois de corrigir URL ou Authorization, use este mesmo endpoint para verificar e reativar; `PATCH { "active": true }` sozinho retorna `verification_required`.

Alterar url ou headers.Authorization invalida a verificação, zera a saúde de todos os canais e coloca health_status=unverified; execute o teste de novo. Alterar somente events, customer_id ou channel_account_ids não reinicia a saúde. PATCH com active=false é a desativação manual. Para reativar, PATCH { "active": true } sozinho retorna verification_required: a reativação passa pelo teste 2xx.

Campos de leitura

GET /api/v1/webhooks, GET /api/v1/webhooks/{id} e a resposta de PATCH retornam somente o estado sanitizado abaixo. O valor de Authorization nunca é devolvido; a resposta de criação 201 é a única que inclui secret — nem um PATCH que troca o secret o devolve.

CampoSignificado
customer_idCliente filtrado pelo endpoint; null significa todos os Clientes da Conta.
channel_account_idsCanais do endpoint; null significa todos os canais da Conta. A lista pode ficar vazia se os canais marcados foram excluídos.
health_statusResumo automático dos canais: unverified, healthy (nenhum canal com falha), degraded (algum canal com falha) ou paused (um canal pausou e nenhum outro entregou com sucesso nas 24 h antes do início das falhas).
failure_streakMaior sequência de falhas entre os canais, em deliveries reais; a recusa de um evento específico não conta.
verified_atMomento do último teste assinado 2xx da configuração atual.
last_success_atMomento do último POST 2xx observado.
last_failure_atMomento da última falha observada.
last_response_codeÚltimo código HTTP observado; null quando não houve resposta.
next_attempt_atPróxima tentativa automática entre os canais que não estão pausados, quando houver.
paused_atMomento em que o endpoint inteiro ficou paused; não significa active=false. Um canal pausado com outro entregando não preenche este campo.
channels_healthCanais com falha, um item por canal (tabela abaixo). Lista vazia quando todos estão saudáveis.

Cada item de channels_health traz o estado da fila daquele canal. A lista vem do maior failure_streak para o menor; no empate, pelo channel_account_id, com null por último.

CampoSignificado
channel_account_idCanal da fila; null é a fila dos eventos sem canal.
health_statuspaused quando o canal está pausado; senão degraded.
failure_streakFalhas seguidas do canal.
next_attempt_atPróxima tentativa do canal; null quando pausado.
paused_atMomento em que o canal pausou.
last_success_atÚltimo POST 2xx de um evento do canal.
last_failure_atÚltima falha do canal.
last_response_codeÚltimo código HTTP do canal; null quando não houve resposta.

Consultar um endpoint de webhook

Lê a configuração e o estado sanitizado de saúde; o segredo HMAC nunca volta em uma leitura.

curl https://botozap.com.br/api/v1/webhooks/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11 \
  -H "X-API-Key: $BOTOZAP_KEY"

Resposta 200

{
  "data": {
    "id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
    "customer_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
    "channel_account_ids": [
      "3d1c6a52-8f0b-4b7e-9a51-2c6e0d4f7a10",
      "9a7e2b14-5c3d-4f81-b6a0-7d2e1f9c3b58"
    ],
    "url": "https://exemplo-integracao.com.br/webhooks/botozap",
    "events": [
      "messages",
      "statuses"
    ],
    "active": true,
    "has_authorization": false,
    "health_status": "degraded",
    "failure_streak": 15,
    "verified_at": "2026-07-14T12:00:00.000Z",
    "last_success_at": "2026-07-14T12:00:00.000Z",
    "last_failure_at": "2026-07-14T12:00:00.000Z",
    "last_response_code": 204,
    "next_attempt_at": "2026-07-14T12:00:00.000Z",
    "paused_at": "2026-07-14T12:00:00.000Z",
    "channels_health": [
      {
        "channel_account_id": "9a7e2b14-5c3d-4f81-b6a0-7d2e1f9c3b58",
        "health_status": "paused",
        "failure_streak": 15,
        "next_attempt_at": null,
        "paused_at": "2026-10-14T17:42:00.000Z",
        "last_success_at": null,
        "last_failure_at": "2026-10-14T17:42:00.000Z",
        "last_response_code": 404
      }
    ],
    "created_at": "2026-07-14T12:00:00.000Z",
    "updated_at": "2026-07-14T12:00:00.000Z"
  }
}

As leituras expõem apenas `health_status`, `failure_streak`, `verified_at`, `last_success_at`, `last_failure_at`, `last_response_code`, `next_attempt_at`, `paused_at`, `channel_account_ids` e `channels_health`; `secret` aparece somente no 201 de criação.

No exemplo, o webhook recebe de dois canais. O canal de testes foi pausado depois de 15 falhas seguidas; o de produção continua entregando. Por isso o resumo é `degraded` com `failure_streak` 15 e `paused_at` nulo: `paused` só aparece quando um canal pausou e nenhum outro entregou com sucesso nas 24 horas antes do início das falhas.

`channels_health` lista só os canais com falha, do maior `failure_streak` para o menor (empate pelo `channel_account_id`, com `null` por último). `channel_account_id: null` é a fila dos eventos sem canal. Lista vazia = todos os canais saudáveis.

Degradação automática

Depois de verificado, o endpoint tem uma fila por canal: cada número do WhatsApp e cada conta do Instagram espera, conta falhas e pausa separadamente. Eventos sem canal (por exemplo, os da WABA que não citam um número) formam uma fila própria, que aparece com channel_account_id: null em channels_health. Se o seu receptor recusa tudo de um número e aceita o outro, só o canal recusado espera e pausa; o outro continua chegando na hora.

Timeout, erro de rede, bloqueio local de configuração e as respostas 408 e 429 contam sempre como falha do canal do evento. Uma resposta HTTP fora de 2xx conta como falha do canal, a menos que haja prova de que ele aceita os outros eventos daquele canal.

Se o seu receptor recusa um evento específico (por exemplo, devolve 404 ou 500 para aquele payload) e aceita os demais do mesmo canal, a recusa é do evento: só ele entra na curva de retry, os outros continuam sendo entregues e a saúde do canal não muda. As provas valem dentro do canal: um 2xx de outro evento do mesmo canal depois da tentativa anterior do evento recusado; um 4xx (exceto 401, 403 e 407) quando o canal aceitou outro evento nos últimos 15 minutos; ou, na primeira tentativa, um 4xx desses quando nenhum outro evento do canal falhou desde o último sucesso dele. Na tentativa 30 (cerca de 24 horas), esse evento vai para exhausted; depois de corrigir o receptor, reenvie-o em Operação no painel ou com POST /api/v1/webhook_deliveries/{id}/replay. A BotoZap não promete ordem de entrega, então um evento em retry pode chegar depois de outros mais novos (veja Confiabilidade).

Cada falha do canal incrementa o streak dele e agenda a próxima tentativa do canal pela curva de 1 / 2 / 4 / 8 / 16 / 32 / 60 minutos, contada pelo streak do canal. No streak 15 o canal pausa: ele para de receber POSTs e o que chega para ele fica retido por 14 dias. Um canal pausado não para os outros. A BotoZap avisa o owner por e-mail quando o pior canal cruza os streaks 5 / 10 / 15, listando os canais com falha.

O endpoint mostra o resumo dos canais: failure_streak é o do pior canal; health_status fica degraded enquanto algum canal tem falha e só vira paused quando um canal pausou e nenhum outro canal entregou com sucesso nas 24 horas antes do início das falhas: sem essa prova de que a URL funciona, a pausa vale para o endpoint inteiro e só sai pelo teste 2xx. Canal tirado da lista ou excluído deixa de contar no resumo e em channels_health; o que ficou retido nele expira no prazo de retenção. Um endpoint degraded com failure_streak de 15 ou mais tem um canal pausado e outro ainda entregando; channels_health diz qual. A pausa não grava active=false. Corrija o receptor e use Testar e ativar (no painel; na API, POST /api/v1/webhooks/{id}/test): um teste 2xx zera o streak de todos os canais e retoma a fila não expirada de cada canal pausado. Trocar url ou Authorization também zera a saúde dos canais e exige novo teste.

Validar a assinatura e deduplicar

Antes de confiar em qualquer entrega, valide o header X-Webhook-Signature: HMAC-SHA256 em hexadecimal, calculado sobre os bytes crus do corpo da requisição com o secret do seu endpoint. Não há prefixo sha256=: o header é só o hex. Compare com crypto.timingSafeEqual (constant-time). Reserializar o JSON antes de comparar muda os bytes e quebra a assinatura.

Rotacionar o secret

Envie PATCH /api/v1/webhooks/{id} com { "secret": "<novo>" } (no SDK, boto.webhooks.update(id, { secret }); na CLI, botozap webhooks update <id> --secret <novo>). A validação é a mesma da criação — 16 a 256 caracteres, sem quebras de linha, 422 invalid_secret caso contrário — e o valor não volta na resposta nem em GET. Gere-o você mesmo, por exemplo com whsec_ + 32 bytes aleatórios em base64url; no painel de Webhooks, Regenerar segredo faz a mesma troca com um secret gerado pela BotoZap.

A troca é imediata e não há janela com duas assinaturas: cada entrega é assinada com o secret vigente no momento da tentativa, inclusive as pendentes e as que estão em retry. Uma tentativa que já estava em voo no instante da troca ainda chega com o secret anterior. Por isso, faça o receptor aceitar os dois secrets, rotacione e só então remova o antigo. A rotação não muda url nem Authorization, então não reinicia a verificação; se o receptor recusar entregas nesse meio tempo, elas seguem o retry normal e contam no failure_streak. Reenviar o mesmo PATCH é seguro.

O receptor abaixo cobre os quatro pontos onde devs mais erram: capturar o corpo cru, validar a assinatura, deduplicar de forma persistente por X-Idempotency-Key (um Set em memória não serve para produção) e só responder 2xx depois de persistir o efeito.

Receptor de webhook (Node.js)

import { createServer } from "node:http";
import { createHmac, timingSafeEqual } from "node:crypto";

const WEBHOOK_SECRET = process.env.BOTOZAP_WEBHOOK_SECRET!; // whsec_... (tela Webhooks)

/**
 * Verifica a assinatura HMAC-SHA256 do BotoZap (header X-Webhook-Signature).
 * IMPORTANTE: calcule o HMAC sobre os BYTES CRUS do corpo — nunca sobre
 * JSON.stringify(JSON.parse(rawBody)), que pode reordenar chaves ou mudar
 * espaçamento e invalidar a assinatura.
 */
function verifyBotozapSignature(
  rawBody: Buffer,
  signatureHeader: string | undefined,
  secret: string,
): boolean {
  if (!signatureHeader) return false;
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(signatureHeader, "utf8");
  const b = Buffer.from(expected, "utf8");
  if (a.length !== b.length) return false;
  return timingSafeEqual(a, b);
}

/**
 * Processe o efeito E registre a X-Idempotency-Key NA MESMA TRANSAÇÃO. Um Set
 * em memória não serve, e inserir só a chave antes do efeito também é
 * incorreto: se o processo cair no meio, o retry parecerá uma duplicata e o
 * efeito será perdido. O padrão relacional é:
 *
 *   BEGIN;
 *   INSERT INTO processed_webhooks (idempotency_key) VALUES ($1)
 *     ON CONFLICT (idempotency_key) DO NOTHING RETURNING idempotency_key;
 *   -- se inseriu: aplique aqui as escritas do evento, na MESMA transação
 *   COMMIT;
 *
 * Em conflito, retorne "duplicate" sem repetir o efeito. Em crash antes do
 * COMMIT, banco reverte chave+efeito juntos e o retry pode processar de novo.
 */
async function processEventOnce(
  idempotencyKey: string,
  event: unknown,
): Promise<"processed" | "duplicate"> {
  throw new Error(
    "implemente uma transação única para idempotencyKey + escritas do evento",
  );
}

const server = createServer((req, res) => {
  const chunks: Buffer[] = [];
  req.on("data", (chunk) => chunks.push(chunk));
  req.on("end", async () => {
    const rawBody = Buffer.concat(chunks); // bytes CRUS — nunca reserializar

    const signatureHeader = req.headers["x-webhook-signature"];
    const signature = Array.isArray(signatureHeader) ? signatureHeader[0] : signatureHeader;
    if (!verifyBotozapSignature(rawBody, signature, WEBHOOK_SECRET)) {
      res.writeHead(401).end();
      return;
    }

    const idempotencyHeader = req.headers["x-idempotency-key"];
    const idempotencyKey = Array.isArray(idempotencyHeader) ? idempotencyHeader[0] : idempotencyHeader;
    if (!idempotencyKey) {
      res.writeHead(400).end();
      return;
    }

    const event = JSON.parse(rawBody.toString("utf8"));
    // Chave + efeito são commitados juntos. Só depois responda: 2xx é o único
    // ACK; fora de 2xx OU timeout = nova tentativa automática.
    await processEventOnce(idempotencyKey, event);

    res.writeHead(200).end();
  });
});

// Ajuste a porta ao seu ambiente antes de subir o processo:
// server.listen(3001);

Auditar entregas

O histórico de entregas fica em GET /api/v1/webhook_deliveries, com o tipo do evento, o status (pending / success / failed / exhausted / limited), o número de tentativas e o código de resposta HTTP do seu servidor. Filtre por endpoint_id (ou o alias webhook_id), status (valor fora da lista responde 422 invalid_status) e event_type, que recebe o nome fino do evento (ex.: whatsapp.message.failed ou webhook.test), não a categoria, e channel_account_id (o canal da entrega; none lista as entregas sem canal, como o teste). Cada linha traz o channel_account_id, e a tela Logs de webhook tem os mesmos filtros. No caminho health-aware, retries continuam após a sétima tentativa com intervalos de 60 minutos;exhausted é reservado a um terminal auditável (por exemplo, expiração do hold), não a um teto de seis tentativas. Uma linha em hold pode expirar após 14 dias com razão terminal auditável. Use esta listagem para depurar entregas que falharam e confirmar o que já foi processado.

Limite de repasse no plano Free

No plano Free, até 300 mensagens recebidas por mês (mês UTC) são repassadas aos seus webhooks. Só contam whatsapp.message.received e instagram.message.received de números reais; o mesmo evento entregue a vários endpoints conta uma vez. Status, CRM, eventos da conta e app_messages não contam, e o Sandbox fica fora. O recebimento no BotoZap nunca para: a mensagem aparece no Inbox e na API normalmente. Nos planos pagos e no teste de 14 dias não há esse limite. Contas Free criadas até 30 de setembro de 2026 passam a ter o limite em 1º de novembro de 2026; as criadas a partir de 1º de outubro já nascem com ele.

Acima do limite, a entrega fica com status limited: não é enviada, não é retentada e não é reenviada sozinha quando você assina. Depois de assinar, reenvie pela tela de Operação ou pela API (abaixo). Filtre com status=limited para ver o que ficou retido. Um aviso por e-mail chega em 80% (240) e em 100% (300), e o medidor aparece na tela Webhooks do painel.

Auditar entregas de webhook

Lista as tentativas de entrega dos seus webhooks — útil para depurar por que um evento não chegou.

curl https://botozap.com.br/api/v1/webhook_deliveries?limit=2 \
  -H "X-API-Key: $BOTOZAP_KEY"

Resposta 200

{
  "data": [],
  "paging": {
    "cursors": {
      "before": "MjAyNi0wNy0xNFQxMjowMDowMC4wMDBa",
      "after": "MjAyNi0wNy0xNFQxMjowMDowMC4wMDBa"
    },
    "next": "MjAyNi0wNy0xNFQxMjowMDowMC4wMDBa",
    "previous": "MjAyNi0wNy0xNFQxMjowMDowMC4wMDBa"
  }
}

`events` (no `POST /api/v1/webhooks` de criação do endpoint) são CATEGORIAS de assinatura ("messages"/"statuses"/…); `event_type` aqui (na auditoria de entregas) é o nome FINO do evento entregue (ex.: "whatsapp.message.received", "whatsapp.message.echo" — mensagem que a equipe enviou pelo app em coexistência, categoria opt-in "app_messages" —, "whatsapp.message.delivered") — não confunda os dois.

Reenviar uma entrega esgotada

Depois de corrigir o receptor, reenvie uma entrega exhausted (ou limited, com saldo no mês) com POST /api/v1/webhook_deliveries/{id}/replay. É o mesmo Reenviar da tela de Operação: a entrega volta para a fila e sai de novo com a mesma X-Idempotency-Key. No SDK, webhookDeliveries.replay(id); no MCP, replay_webhook_delivery.

Reenviar uma entrega esgotada

Depois de corrigir o seu sistema, reenvia um evento que esgotou as tentativas. É o mesmo Reenviar da tela de Operação.

curl https://botozap.com.br/api/v1/webhook_deliveries/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11/replay \
  -X POST \
  -H "X-API-Key: $BOTOZAP_KEY"

Resposta 200

{
  "data": {
    "id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
    "status": "pending",
    "replayed": true
  }
}

Reenvia entregas com `status` `exhausted` (esgotou as tentativas) ou `limited` (cortada pelo limite de eventos do mês). Ache as esgotadas com `GET /api/v1/webhook_deliveries?status=exhausted`.

O evento sai de novo com a mesma `X-Idempotency-Key`: se o seu sistema já tinha processado, deduplique por ela.

Entrega em outro status responde `409 delivery_not_replayable`; chamar de novo depois do reenvio também. Sem saldo no limite do mês, `409 forward_limit_reached`.

Quer ligar uma Entrega diretamente ao seu runtime? Veja o exemplo executável em Endpoint para agentes, com PostgreSQL, dedupe e worker sem polling.