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
- Abra Configurações › Webhooks e clique em Novo webhook.
- Em URL do endpoint, cole o endereço que o desenvolvedor passou.
- Em Cliente, deixe Todos os clientes ou escolha um cliente para receber só os avisos dos canais dele.
- Em Canais, deixe Todos os canais ou escolha Escolher canais e marque os canais que este endereço deve receber (veja abaixo).
- Em Eventos, marque os avisos que o sistema precisa. Mensagens recebidas e Status de envio já vêm marcados.
- Clique em Criar webhook.
- A janela Segredo de assinatura mostra o segredo deste webhook. Copie e entregue ao desenvolvedor (veja abaixo para que serve).
- 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
- 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.
- 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.
- 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.
- 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.
- No menu do webhook, clique em Regenerar segredo.
- Copie o segredo novo na janela Segredo de assinatura e entregue ao desenvolvedor.
- 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.
