Resumo
Os webhooks no Wati permitem que você receba atualizações em tempo real sobre mensagens e seus status, enviando dados de eventos para o seu servidor. Este guia explica quais eventos você pode rastrear, como configurar um webhook e como funcionam os callbacks baseados em sessão para que você possa processar com confiabilidade a atividade de mensagens em seu sistema.
Instruções
Quais eventos os webhooks do Wati podem capturar?
Os webhooks do Wati notificam seu sistema externo quando eventos específicos ocorrem em sua conta Wati. Quando um evento acontece, o Wati envia um payload de callback para a URL de webhook que você configurou. Seu sistema pode usar essas informações para rastrear mensagens, monitorar status de mensagens e manter-se atualizado sobre alterações na conta do WhatsApp.
O Wati suporta os seguintes eventos de webhook:
Eventos de mensagem e conversação
Mensagem Recebida – Quando um cliente envia uma mensagem.
Nova Mensagem de Contato – Quando um novo contato envia uma mensagem.
Mensagem de Sessão Enviada – Quando uma mensagem de sessão é enviada.
Mensagem de Modelo Enviada – Quando uma mensagem de modelo (template) é enviada.
Mensagem Enviada foi ENTREGUE – Quando uma mensagem enviada é entregue.
Mensagem Enviada foi Lida – Quando uma mensagem enviada é lida.
Mensagem Enviada foi RESPONDIDA – Quando um cliente responde a uma mensagem enviada.
Falha no envio de Mensagem de Sessão – Quando uma mensagem de sessão falha ao ser enviada.
Falha no envio de Mensagem de Modelo – Quando uma mensagem de modelo falha ao ser enviada.
Eventos de modelo
Atualização de Status de Modelo – Quando o status de um modelo muda.
Atualização de Qualidade de Modelo – Quando a classificação de qualidade de um modelo muda.
Atualização de Categoria de Modelo – Quando a categoria de um modelo muda.
Eventos de conta do WhatsApp e número de telefone
Revisão de Conta do WhatsApp Atualizada – Quando o status de revisão de uma conta do WhatsApp muda.
Atualização de Qualidade de Número de Telefone – Quando a classificação de qualidade de um número de telefone muda.
Conta WABA Excluída – Quando uma conta WhatsApp Business (WABA) é excluída.
Conteúdo da Conta WABA Atualizado – Quando o conteúdo de uma WABA é atualizado.
Número de Telefone Excluído – Quando um número de telefone é excluído.
Capacidade Comercial Atualizada – Quando uma capacidade comercial é atualizada.
Outros eventos
Chatbot Acionado – Quando um chatbot é acionado.
URL de CTA clicada – Quando um cliente clica em uma URL de CTA.
Botão de CTA clicado (BSUID) – Quando um cliente clica em um botão de CTA.
Status de Chamada – Quando o status de uma chamada do WhatsApp muda.
Resposta à Solicitação de Contato – Quando um cliente responde a uma solicitação de contato.
Pagamento do WhatsApp Capturado – Quando um pagamento do WhatsApp é capturado.
Eventos de webhook adicionais para BSUID
O Wati também suporta eventos de webhook adicionais para BSUID (Business-Scoped User ID).
Estes incluem:
Mensagem Recebida (BSUID)
Nova Mensagem de Contato (BSUID)
Mensagem de Sessão Enviada (BSUID)
Mensagem de Sessão Enviada v2 (BSUID)
Mensagem de Modelo Enviada (BSUID)
Mensagem de Modelo Enviada v2 (BSUID)
Chatbot Acionado (BSUID)
Botão de CTA clicado (BSUID)
Status de Chamada (BSUID)
Para detalhes sobre eventos individuais e seus payloads de callback, consulte nossa documentação de webhook.
Como adicionar um webhook no Wati
Siga estas etapas para configurar um webhook:
Faça login no seu painel do Wati.
Vá para Connectors (Conectores) e clique em Webhooks.
Clique em Add Webhook (Adicionar Webhook).

Insira sua URL de webhook completa.
Defina o status como Enabled (Ativado). Os status de webhook podem ser Enabled (Ativado), Disabled (Desativado) e Defective (Com defeito).
Selecione os eventos que você deseja capturar.

Clique em Save (Salvar).
Como testar seu webhook
Após adicionar o webhook, você pode testar a conexão:
Use a opção Trigger sample callback (Acionar callback de exemplo).

O Wati enviará um payload de exemplo para a sua URL de webhook.

Verifique se seu servidor recebe e processa o payload corretamente.
Entendendo webhooks baseados em sessão
Na API do WhatsApp Business, as conversas são rastreadas como sessões de 24 horas. Uma sessão começa quando uma mensagem comercial é entregue.
Tipos de sessões
Sessão ativa
Tanto a empresa quanto o cliente trocaram pelo menos uma mensagem.
Exemplo: Uma empresa envia uma mensagem de modelo e o cliente responde.
Sessão inativa
Apenas uma das partes enviou uma mensagem e a outra não respondeu.
Exemplo: Uma empresa envia uma mensagem de modelo, mas o cliente não responde.
Nota: Os callbacks de webhook podem variar dependendo se a sessão está ativa ou inativa.
Resposta do webhook e lógica de nova tentativa
Para garantir uma entrega confiável, seu webhook deve responder corretamente.
Seu servidor deve retornar uma resposta
200 OKpara confirmar que o evento foi recebido.
Se uma resposta
200não for recebida:O Wati tenta reenviar o evento.
As tentativas podem ocorrer até 144 vezes.
As tentativas de reenvio ocorrem em intervalos de 10 minutos.
Se houver mais de 100 falhas consecutivas:
O webhook é marcado como Defective (Com defeito).
Você receberá uma notificação por e-mail.
Se todas as tentativas de reenvio falharem, o evento não será mais enviado.
Melhores práticas
Certifique-se de que seu endpoint de webhook esteja sempre disponível e responsivo.
Registre os payloads recebidos para facilitar a depuração.
Trate eventos duplicados, pois as tentativas de reenvio podem enviar o mesmo payload mais de uma vez.
Valide as solicitações recebidas para garantir que elas sejam originadas do Wati.
Essa configuração ajuda você a manter seus sistemas sincronizados com a atividade de mensagens em tempo real no Wati.
Perguntas Frequentes (FAQs)
Eventos e configuração de webhook
1. Que tipos de eventos os webhooks do Wati podem capturar?
Os webhooks do Wati podem capturar eventos de mensagem e conversação, eventos de modelo, eventos de conta do WhatsApp e número de telefone, e outros eventos. Quando um evento suportado ocorre, o Wati envia um payload de callback para a URL de webhook que você configurou.
2. Quais status de webhook estão disponíveis no Wati?
O Wati suporta três status de webhook:
Enabled (Ativado) – O webhook está ativado.
Disabled (Desativado) – O webhook está desativado.
Defective (Com defeito) – O webhook foi marcado como defeituoso após repetidas falhas de entrega.
3. O Wati suporta eventos de webhook adicionais para BSUID?
Sim. O Wati suporta eventos de webhook adicionais para Business-Scoped User ID (BSUID). Consulte a documentação de webhook para detalhes sobre eventos BSUID individuais e seus payloads de callback.
Webhooks baseados em sessão
4. Qual é a diferença entre uma sessão ativa e uma sessão inativa?
Uma sessão ativa ocorre quando tanto a empresa quanto o cliente trocaram pelo menos uma mensagem.
Uma sessão inativa ocorre quando apenas uma das partes enviou uma mensagem e a outra parte não respondeu.
5. Os callbacks de webhook variam entre sessões ativas e inativas?
Sim. Os callbacks de webhook podem variar dependendo se a sessão do WhatsApp está ativa ou inativa. Uma sessão do WhatsApp começa quando uma mensagem comercial é entregue e dura 24 horas.
Resposta do webhook e solução de problemas
6. O que acontece se meu endpoint de webhook não retornar uma resposta 200 OK?
Seu servidor deve retornar uma resposta 200 OK para confirmar que recebeu um evento de webhook. Se o Wati não receber essa resposta, ele tentará reenviar o evento até 144 vezes em intervalos de 10 minutos.
Se houver mais de 100 falhas consecutivas, o Wati marca o webhook como Defective (Com defeito) e envia uma notificação por e-mail. Se todas as tentativas de reenvio falharem, o Wati para de enviar o evento.
7. Como posso melhorar a confiabilidade do webhook?
Mantenha seu endpoint de webhook disponível e responsivo, registre os payloads de callback recebidos para facilitar a depuração, trate eventos duplicados para evitar o processamento do mesmo payload várias vezes e valide as solicitações recebidas para garantir que sejam originadas do Wati.
Did this answer your question?