Receber eventos do WhatsApp (Saída)

Os webhooks de Saída entregam eventos do WhatsApp para uma URL sua, em tempo real. Toda vez que algo acontece (uma mensagem chega, um grupo muda, uma chamada começa), o PragmaZ envia o evento para o seu endpoint.

Tudo isso fica na tela Webhooks, na aba Saída.

Criar um endpoint

1. No menu lateral, abra Webhooks e fique na aba Saída.

2. Clique em Novo endpoint.

3. Em URL de destino, informe a URL do seu sistema que vai receber os eventos. Em produção, a URL precisa ser HTTPS.

4. Opcional: preencha a Descrição para identificar o endpoint.

5. Em Eventos a receber, marque os eventos desejados. Use Selecionar todos para marcar um grupo inteiro. É preciso escolher ao menos um evento.

6. Opcional: em Dispositivos (deixe vazio pra todos), escolha de quais números você quer receber eventos. Deixe vazio para receber de todos.

7. Clique em Criar endpoint.

📸 Captura necessária: modal “Criar endpoint outbound” com o campo de URL preenchido e alguns eventos marcados na lista agrupada.

Guardar o signing secret

Ao criar o endpoint, o painel mostra uma vez só o Signing secret, com o aviso de que ele não será exibido novamente. Copie e guarde esse valor com segurança e clique em Guardei — Fechar. Você usa o secret para validar a assinatura dos eventos recebidos.

Caution

O signing secret aparece apenas no momento da criação. Se você perder o valor, gere um novo na tela de detalhe do endpoint (rotação de secret).

Como cada entrega chega

Cada entrega ao seu endpoint é:

• Assinada com HMAC-SHA256 — valide o cabeçalho Pragmaz-Signature com o seu signing secret. A entrega também traz o cabeçalho Pragmaz-Timestamp (em segundos).
• Com timestamp para proteção contra replay — valide que o Pragmaz-Timestamp está dentro de uma janela curta (recomendado 5 minutos) e rejeite entregas fora dela. Cada evento também tem um id único (no corpo) que você pode usar para descartar duplicatas do seu lado.
• Reenviada automaticamente em caso de falha — até 12 tentativas, com espera crescente (de 30 segundos até 24 horas).

Validar e acompanhar entregas

Abra um endpoint para ver o detalhe. Lá você acompanha o histórico de entregas (com filtro), as métricas (latência e códigos de status retornados pelo seu servidor) e os eventos selecionados.

Se uma entrega falhar, use o botão Reenviar para tentar de novo a mesma entrega.

Status do endpoint e auto-desativação

Cada cartão de endpoint tem uma etiqueta de status: Ativo, Desativado ou Auto-desativado. Se o seu endpoint falhar 30 vezes seguidas, o PragmaZ o desativa automaticamente para evitar entregas inúteis.

Depois de corrigir o problema no seu lado, abra o endpoint e clique em Habilitar para voltar a receber eventos (isso zera a contagem de falhas consecutivas).

📸 Captura necessária: cartão de um endpoint de saída mostrando a URL, a pílula de status “Ativo”, a contagem de eventos, de envios e a porcentagem de sucesso.

Veja também

Disparar ações por HTTP (Entrada)

Referência de webhooks

Gerenciar e diagnosticar dispositivos