Navegar na CentralWebhooks

Webhooks

Entenda o que é um webhook, cadastre o endereço do seu sistema, escolha de quais canais ele recebe, acompanhe a saúde das entregas e troque o segredo com segurança.

Atualizado em

Um webhook é um aviso automático que o BotoZap manda para outro sistema no instante em que algo acontece: chegou uma mensagem, uma mensagem foi entregue, um contato mudou de etapa no funil. Em vez de o seu sistema ficar perguntando ao BotoZap "tem novidade?", o BotoZap avisa sozinho, na hora.

Para isso, o seu sistema precisa ter um endereço de internet preparado para receber esses avisos. Quem monta esse endereço é o desenvolvedor da integração. Você cadastra o endereço aqui e escolhe quais avisos ele recebe.

Os webhooks ficam em Configurações › Webhooks.

Antes de começar

  • Cadastrar e editar webhook é só para Administrador, porque o webhook manda as mensagens e os dados da conta para outro sistema. Ver e regenerar o segredo de assinatura e definir o Cabeçalho Authorization também. Se você trabalha sozinho, você já é o Administrador da conta. Quem é Operador vê os webhooks, testa, desativa e exclui: na tela aparece Só Administrador cria e edita webhooks, e no menu do webhook aparece Só Administrador pode ver o segredo.
  • Peça ao desenvolvedor o endereço (a URL) que vai receber os avisos. Ele precisa começar com https://.
  • O webhook vale para a conta inteira por padrão: todos os clientes e todos os canais. Se quiser, você limita um webhook a um cliente só e escolhe de quais canais (números do WhatsApp e contas do Instagram) ele recebe.

Que avisos existem

Ao cadastrar, você marca em Eventos quais avisos esse endereço recebe:

  • Mensagens recebidas: quando um contato manda uma mensagem, no WhatsApp ou no Instagram. No Instagram, inclui também os comentários nos seus posts e as respostas públicas das regras de Comentários → DM.
  • Status de envio: quando uma mensagem que você mandou é enviada, entregue, lida ou falha. No Instagram não existe o aviso de entregue, porque o Instagram não confirma a entrega: a mensagem passa de enviada para lida.
  • Funil (CRM): mudança de etapa do contato, oportunidades, demandas e agendamentos.
  • Saúde da WABA: só do WhatsApp. Avisa quando um número termina de conectar ao BotoZap, além de bloqueios, restrições e mudanças de limite da sua conta do WhatsApp na Meta (a WABA é a conta do WhatsApp Business do seu negócio na Meta). O aviso de número conectado avisa o sistema do desenvolvedor assim que o seu cliente conclui o link de conexão.
  • Mensagens do app (coexistência): quando a equipe envia, edita ou apaga uma mensagem pelo app WhatsApp Business, num número que continua no app. Só chega se esta opção estiver marcada.

Passo a passo: cadastrar um webhook

  1. Abra Configurações › Webhooks e clique em Novo webhook.
  2. Em URL do endpoint, cole o endereço que o desenvolvedor passou.
  3. Em Cliente, deixe Todos os clientes ou escolha um cliente para receber só os avisos dos canais dele.
  4. Em Canais, deixe Todos os canais ou escolha Escolher canais e marque os canais que este endereço deve receber (veja abaixo).
  5. Em Eventos, marque os avisos que o sistema precisa. Mensagens recebidas e Status de envio já vêm marcados.
  6. Clique em Criar webhook.
  7. A janela Segredo de assinatura mostra o segredo deste webhook. Copie e entregue ao desenvolvedor (veja abaixo para que serve).
  8. Quando o desenvolvedor confirmar que o sistema está pronto, clique em Testar e ativar. Se ainda não estiver pronto, clique em Deixar para depois.

O teste manda um aviso de exemplo para o endereço. Se o sistema responder que recebeu, aparece Teste 2xx confirmado. Webhook ativado. e o webhook começa a receber os avisos de verdade. "2xx" é o código que um sistema devolve quando recebeu o aviso com sucesso.

Importante: enquanto o teste não der certo, o webhook fica em Aguardando teste e não recebe nenhum aviso real. É assim de propósito: o BotoZap só manda dados depois de confirmar que o endereço é o certo e está funcionando.

Escolher os canais

Um canal é um número do WhatsApp ou uma conta do Instagram conectada ao BotoZap. Em Canais:

  • Todos os canais (o padrão): o webhook recebe os avisos de todos os canais da conta, inclusive dos que você conectar depois.
  • Escolher canais: aparece a lista dos canais, cada um com uma caixa para marcar. Os números do WhatsApp aparecem com o nome e o telefone (por exemplo, Loja Centro · +55 51 8160-0890) e as contas do Instagram, pelo @ (por exemplo, @lojacentro). O webhook recebe só os avisos dos canais marcados. Marque ao menos um.

Se você escolheu um cliente em Cliente, a lista mostra só os canais desse cliente. Ao trocar o cliente de um webhook com canais escolhidos, os canais marcados que não são do novo cliente saem da escolha e a tela avisa quantos foram desmarcados: marque os canais de novo antes de salvar.

Avisos da conta do WhatsApp que não são de um número específico, como a aprovação de um template, chegam se algum número marcado for dessa conta do WhatsApp.

Se um canal marcado for excluído, ele sai da lista do webhook, e o webhook continua recebendo só dos canais que sobraram. Ele não passa a receber de todos os canais sozinho. Se não sobrar nenhum, o webhook mostra o aviso Nenhum canal marcado: este webhook não recebe eventos: abra Editar e marque outros canais ou escolha Todos os canais.

Mudar os canais não exige novo teste.

Separar o número de testes do número de produção

Um caso comum: o desenvolvedor tem um número de testes dele e o número do cliente na mesma conta, os dois no mesmo webhook. O sistema dele só sabia tratar os avisos do número do cliente e recusava os do número de testes. Para não misturar:

  • marque no webhook de produção só o número do cliente, em Escolher canais; ou
  • crie um webhook para cada número, cada um apontando para o sistema certo (por exemplo, um endereço de testes e um de produção).

Mesmo sem separar, um número recusado não atrasa o outro: cada canal tem a sua fila (veja Um canal pausado, abaixo). Mas separar evita falhas e avisos por e-mail à toa.

Para que serve o segredo

O segredo é uma senha que o BotoZap usa para "assinar" cada aviso. O sistema que recebe confere a assinatura e, assim, sabe que o aviso veio mesmo do BotoZap, e não de alguém tentando se passar por ele.

Diferente da chave de API, o segredo pode ser visto de novo: no menu do webhook, clique em Revelar segredo.

Saúde do webhook

A coluna Status mostra como estão as entregas:

  • Aguardando teste: o webhook ainda não passou no teste. Nenhum aviso real é enviado.
  • Saudável: os avisos estão chegando.
  • Instável: o sistema de destino está recusando ou não está respondendo os avisos de algum canal. Cada aviso espera a resposta por até 10 segundos. O BotoZap continua tentando, com intervalos cada vez maiores. Um aviso específico recusado não deixa o webhook instável (veja abaixo).
  • Um canal pausado (ou 2 canais pausados, e assim por diante): esses canais pararam depois de 15 falhas seguidas, e os outros canais continuam recebendo normalmente (veja abaixo).
  • Pausado: um canal chegou a 15 falhas seguidas e nenhum outro canal recebeu avisos com sucesso nesse período, sinal de que o sistema de destino está fora do ar. O BotoZap parou de mandar avisos para esse endereço e guarda os avisos novos por até 14 dias, esperando o sistema voltar.
  • Inativo manualmente: alguém da equipe desativou o webhook.

Abaixo do status aparecem detalhes que ajudam o desenvolvedor, como Última resposta do sistema (quando nenhum canal está com falha), Última falha, Verificado (data do último teste que deu certo) e Último sucesso. Quando algum canal tem falha, aparece uma linha por canal, com o nome do canal e a situação dele, por exemplo:

  • Atendimento · +55 11 95213-2789 — 3 falhas seguidas, nova tentativa às 14:32: o BotoZap vai tentar de novo esse canal no horário mostrado.
  • Loja · +55 11 12345-6789 — pausado após 15 falhas (HTTP 400): esse canal parou (veja abaixo). O número entre parênteses é a última resposta do seu sistema para esse canal.

Avisos que não são de nenhum canal aparecem como Eventos sem canal.

Um canal pausado

Cada canal do webhook tem a sua própria fila de entregas. Se o sistema de destino recusa os avisos de um número, o BotoZap espera e tenta de novo só esse número; os avisos dos outros canais continuam chegando na hora.

Na 15ª falha seguida de um canal, esse canal é pausado: o BotoZap para de mandar os avisos dele e os guarda por até 14 dias. Os outros canais não param. O webhook só fica Pausado por inteiro quando nenhum outro canal recebeu avisos com sucesso nas 24 horas antes de as falhas começarem: aí o problema é o sistema de destino, não um número. Se você tirar um canal da lista do webhook ou excluir o canal, ele deixa de aparecer na saúde do webhook.

O dono da conta recebe um e-mail quando um canal chega a 5, 10 e 15 falhas seguidas, com a lista dos canais com falha.

Para retomar, corrija o sistema de destino e use o teste do webhook (veja o passo a passo abaixo). Um teste que dá certo retoma todos os canais pausados de uma vez.

Quando um aviso específico é recusado

Às vezes o sistema de destino funciona, mas recusa um aviso específico, por exemplo respondendo 404 para uma mensagem que ele não sabe tratar. Nesse caso o BotoZap tenta de novo só esse aviso, com intervalos cada vez maiores, e os outros continuam chegando normalmente. O status do webhook não muda por causa disso. A conta é feita dentro de cada canal: se o sistema aceita outros avisos do mesmo número, a recusa é daquele aviso; se recusa tudo de um número, é o canal que entra em falha.

Depois de 30 tentativas (cerca de 24 horas), esse aviso fica como Esgotado em Configurações › Logs de webhook. Peça ao desenvolvedor para conferir o motivo da recusa com o código de resposta e o horário mostrados ali. Com o sistema corrigido, reenvie o aviso em Operação. O desenvolvedor também pode reenviar pela API (POST /v1/webhook_deliveries/{id}/replay) ou pelo MCP (replay_webhook_delivery).

Passo a passo: retomar um canal ou um webhook pausado

  1. Peça ao desenvolvedor para corrigir o sistema que recebe os avisos. A linha de cada canal, a Última resposta e a Última falha ajudam a achar o problema.
  2. Com o sistema corrigido, abra o menu do webhook (Ações do webhook, o botão de três pontos) e clique no item de teste. Com algum canal pausado e outros recebendo, ele se chama Testar e retomar canais; em um webhook Pausado, Testar e ativar.
  3. Se o teste der certo, aparece a confirmação do teste (por exemplo Teste 2xx confirmado e canais pausados retomados.) junto com quantos avisos guardados foram retomados, por exemplo 3 entregas retidas foram retomadas. Todos os canais pausados voltam a receber, o status volta para Saudável e os avisos guardados nos últimos 14 dias voltam a ser enviados sozinhos. Não é preciso reenviar nada.

Em um webhook Saudável, o mesmo item do menu se chama Testar novamente: ele confere o endereço sem mudar nada, e a confirmação é Teste 2xx confirmado.

Um teste que falha não piora a saúde do webhook: ele só mostra o motivo, por exemplo O endpoint respondeu 404. Esperado 2xx.

Passo a passo: desativar e ativar de novo

  • Para parar os avisos por um tempo, abra o menu do webhook e clique em Desativar. A mensagem Webhook desativado. confirma, e o status passa a Inativo manualmente.
  • Para voltar, abra o menu e clique em Testar e ativar. O webhook só volta a receber avisos depois de um teste que dê certo.

Editar

No menu do webhook, clique em Editar, ajuste e clique em Salvar alterações.

Se você trocar a URL do endpoint, o webhook volta para Aguardando teste, e a tela avisa Webhook salvo. Faça um novo teste 2xx antes de receber eventos. Depois, use Testar e ativar no menu do webhook. Mudar só os eventos, o cliente ou os canais não exige novo teste.

Passo a passo: trocar o segredo

Troque o segredo se ele vazou ou se alguém que o conhecia saiu da equipe.

  1. Combine com o desenvolvedor antes. A troca vale na hora: enquanto o sistema de destino não tiver o segredo novo, ele recusa os avisos, que entram em nova tentativa e contam como falha na saúde do webhook.
  2. No menu do webhook, clique em Regenerar segredo.
  3. Copie o segredo novo na janela Segredo de assinatura e entregue ao desenvolvedor.
  4. Clique em Pronto.

O segredo antigo para de valer no mesmo instante.

Excluir

No menu do webhook, clique em Excluir e confirme em Excluir webhook. O BotoZap para de mandar avisos para esse endereço na hora, e a exclusão não pode ser desfeita.

Conferir as entregas

Cada aviso enviado fica registrado em Configurações › Logs de webhook, com a situação, o código de resposta e o número de tentativas. Veja Registros de API, Meta e webhooks.

Problemas comuns

Aparece "A URL precisa usar https://." O endereço precisa ser seguro. Peça ao desenvolvedor um endereço que comece com https://.

O teste falha com "Não foi possível entregar o evento de teste." O BotoZap não conseguiu falar com o endereço: ele pode estar fora do ar, errado ou bloqueado. Peça ao desenvolvedor para conferir.

Aparece "Muitos testes de webhook. Aguarde um instante e tente novamente." Há um limite de testes seguidos. Espere um pouco e tente de novo.

O webhook está Saudável, mas o sistema não recebe um tipo de aviso. Abra Editar e confira se o evento está marcado e se o Cliente e os Canais são os certos.

Um número para de receber avisos e o outro continua. Veja a linha do canal abaixo do status: se aparece pausado após 15 falhas, o sistema de destino recusou os avisos desse número. Corrija o sistema e use o teste do webhook para retomar.

Aparece "Webhooks indisponíveis agora." O BotoZap não conseguiu carregar a lista neste momento. Seus webhooks continuam cadastrados e recebendo avisos; atualize a página em instantes.

Aparece "Não foi possível carregar a lista de clientes." Sem essa lista, a tela não consegue mostrar com segurança para qual cliente cada webhook vale. Por isso Novo webhook e Editar somem até a lista carregar, e a coluna Cliente e canais mostra Cliente indisponível nos webhooks limitados a um cliente. Nada muda nos webhooks; atualize a página em instantes.

Aparece "Não foi possível carregar a lista de canais." Pelo mesmo motivo, Novo webhook e Editar somem até a lista de canais carregar, para não mudar por engano os canais de um webhook. Nada muda nos webhooks; atualize a página em instantes.