Como os webhooks funcionam
Quando um evento de disparo ocorre, o PanÐá Zap envia uma requisição HTTPPOST para a URL que você configurou. Seu servidor deve responder com um código de status 2xx. Atualmente, o PanÐá Zap não tenta reenviar entregas que falharam, então garanta que seu endpoint seja confiável e responda rapidamente.
Existem dois tipos de webhooks:
Configurar um webhook de canal
Payload de evento de mensagem
Quando uma mensagem chega em um canal com webhooks ativados, o PanÐá Zap envia um payload semelhante ao seguinte:ticket.id está sempre presente no payload do webhook para todos os tipos de canal: WhatsApp, Instagram, Messenger, Telegram e e-mail. Você sempre pode usá-lo para correlacionar o evento com um registro de ticket através da API de Tickets.Configurar webhooks globais
Os webhooks globais permitem que você assine múltiplos tipos de evento em toda a sua conta, não apenas em um canal.- No menu Configuração, abra Configurações, vá para a aba Integrações e clique em Webhooks.
- Em Webhook principal, ative Ativar webhook e preencha a URL do Webhook.
- Ative Webhook mensagens para receber os eventos de mensagem.
- Para receber o status das mensagens enviadas pelo WhatsApp oficial (enviada, entregue, lida, falhou), ative Webhook status de envio. Veja Status de envio das mensagens.
- Em Eventos de canal e usuário, ative só os eventos de que você precisa.
- Clique em Salvar.
Status de envio das mensagens
Com Webhook status de envio ligado (em Configuração → Configurações → aba Integrações → Webhooks, junto da URL do Webhook), o PanÐá Zap avisa o seu sistema quando cada mensagem enviada é aceita, entregue, lida ou falha, com o motivo do erro.- Por enquanto, vale só para o WhatsApp oficial direto.
- Cada mensagem enviada gera até 3 avisos, inclusive as de campanha.
- Os avisos podem chegar fora de ordem: use o horário de cada um para ordenar.
- Se o seu endereço não responder em 10 segundos, o aviso não é reenviado. Se ele demorar a responder e os avisos acumularem, os excedentes são descartados.
Segurança
As URLs de webhook devem ser publicamente acessíveis via HTTPS. Por padrão, o PanÐá Zap não envia um cabeçalho de assinatura. Para proteger seu endpoint:- Restringir por IP: configure seu servidor ou firewall para aceitar apenas requisições
POSTvindas dos endereços IP de saída do PanÐá Zap. - Token secreto na URL: incorpore um token longo e aleatório no caminho da URL ou como um parâmetro de consulta (por exemplo,
https://seuservidor.com.br/webhooks/pandazap?token=abc123). Verifique sua presença em toda requisição recebida.
Alternativa de polling
Se sua infraestrutura não pode expor um endpoint HTTPS público, você pode fazer polling na API periodicamente:showAllMessages, o ID do atendimento vai no corpo, no campo ticket (ou em ticketId, com o mesmo valor). Sem o ID, a rota responde 400 com ERR_MISSING_TICKET.
Faça polling em um intervalo razoável (por exemplo, a cada 30 a 60 segundos). listTickets e showAllMessages não têm limite por minuto, mas consultas muito frequentes geram carga desnecessária; para casos sensíveis à latência, prefira os webhooks.
Correlacionando eventos com seus registros
Inclua umexternalKey único em toda requisição de API que envia uma mensagem. Quando o webhook de entrega disparar, o payload conterá o mesmo externalKey: use-o para relacionar o evento do webhook de volta ao registro de envio original no seu sistema, sem depender de IDs internos do PanÐá Zap.
