Em vez de fazer polling na API em busca de novas atividades, você pode configurar o PanÐá Zap para enviar eventos ao seu servidor no momento em que algo acontece — uma nova mensagem chega, o status de um ticket muda, uma mensagem é entregue, ou uma mensagem é lida. Isso é chamado de webhook.
Como os webhooks funcionam
Quando um evento de disparo ocorre, o PanÐá Zap envia uma requisição HTTP POST 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.
- Vá para Configurações → API.
- Ative a chave Webhooks.
- Insira sua URL de webhook.
- Ative Mensagens de Webhook se quiser receber eventos de mensagens.
- Em Eventos de Canal e Usuário, ative os tipos de evento individuais que você precisa:
- Criar / Atualizar Canal
- Criar / Atualizar Usuário
- Criar / Atualizar / Renovar API
- Clique em Salvar.
Tipos de evento globais disponíveis:
Assine apenas os eventos que você realmente utiliza. Toda chamada de webhook adiciona carga ao seu servidor — eventos desnecessários desperdiçam largura de banda e aumentam o overhead de processamento.
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
POST vindas 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://yourserver.com/hooks/panda-zap?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:
Faça polling em um intervalo razoável (por exemplo, a cada 30–60 segundos) para evitar atingir limites de taxa. Os webhooks são fortemente preferíveis para casos de uso sensíveis à latência.
Inclua um externalKey ú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. 
