Webhooks

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

• Ver e regenerar o segredo de assinatura é só para Administrador. Se você trabalha sozinho, você já é o Administrador da conta. Quem é Operador cadastra, edita, testa, desativa e exclui webhooks, mas não vê o segredo: ao cadastrar, aparece Webhook criado. Só Administrador pode ver o segredo de assinatura; peça o segredo e teste o webhook para ativá-lo., e no menu do webhook aparece Só Administrador pode ver o segredo. Quando o webhook tem cabeçalho Authorization (configurado pela API), só Administrador muda o endereço, porque o cabeçalho acompanha a URL; o Operador ainda muda os eventos.
• 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. Se quiser, você limita um webhook a um cliente só.

Que avisos existem

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

• Mensagens recebidas: quando um contato manda uma mensagem.
• Status de envio: quando uma mensagem que você mandou é enviada, entregue, lida ou falha.
• Funil (CRM): mudança de etapa do contato, oportunidades, demandas e agendamentos.
• Saúde da WABA: 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).

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 números dele.
4. Em Eventos, marque os avisos que o sistema precisa. Mensagens recebidas e Status de envio já vêm marcados.
5. Clique em Criar webhook.
6. A janela Segredo de assinatura mostra o segredo deste webhook. Copie e entregue ao desenvolvedor (veja abaixo para que serve).
7. 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.

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 recusou ou não respondeu alguns avisos seguidos. O BotoZap continua tentando, com intervalos cada vez maiores.
• Pausado: foram 15 falhas seguidas. 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: Sequência de falhas, Última resposta do sistema, Última falha, Próxima tentativa, Verificado (data do último teste que deu certo), Último sucesso, Instabilidade desde e Pausado desde.

Passo a passo: reativar um webhook pausado

1. Peça ao desenvolvedor para corrigir o sistema que recebe os avisos. As colunas Última resposta e Ú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 em Testar e ativar.
3. Se o teste der certo, aparece Teste 2xx confirmado e webhook ativado. junto com quantos avisos guardados foram retomados, por exemplo 3 entregas retidas foram retomadas. O status volta para Saudável e esses avisos, guardados nos últimos 14 dias, voltam a ser enviados sozinhos. Não é preciso reenviar nada.

Em um webhook Saudável ou Instá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 ou o cliente 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 é o certo.

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 mostra Cliente indisponível nos webhooks limitados a um cliente. Nada muda nos webhooks; atualize a página em instantes.