Melhores práticas: webhooks confiáveis e integrações escaláveis

Como construir webhooks que não perdem nem duplicam eventos: assinatura HMAC, idempotência, retentativas e resposta rápida.

Jun 26, 2026

Veja este passo no vídeo · Boas práticas de segurança

Para que serve

Os webhooks do Omnifox enviam eventos em tempo real (mensagens, conversas e contatos) para o seu próprio sistema, sem que você precise consultar a API o tempo todo. Bem construídos, são a espinha dorsal de uma integração escalável; mal construídos, perdem eventos ou duplicam dados. Este guia reúne as práticas que recomendamos para produção.

Requisitos

  • Um papel com acesso a Configurações → Webhooks (acesso à API de desenvolvedor).
  • Um endpoint HTTPS público que responda rápido (idealmente < 5s).
  • Capacidade de validar assinaturas HMAC-SHA256 no seu backend.

Passos

  1. Acesse Configurações → Webhooks e clique em Novo webhook.
  2. Cole a URL de destino (sempre HTTPS).
  3. Escolha os eventos que precisa: message.received, message.sent, conversation.created, conversation.closed, contact.created, contact.updated. Assine apenas o que for usar.
  4. Copie e guarde o segredo de assinatura (whsec_…) no seu cofre. O Omnifox assina cada envio com ele.
  5. Configure a estratégia de retentativas (exponencial recomendado) e o máximo de retentativas (padrão 5).
  6. Salve e use Enviar teste para disparar um test.ping.

Verificação

O Omnifox assina o corpo com HMAC-SHA256 e o envia no cabeçalho X-Omnifox-Signature; o tipo de evento vai em X-Omnifox-Event. No seu endpoint, recalcule o HMAC do corpo cru com o seu segredo e compare em tempo constante. Se não coincidir, retorne 401. Confira os registros de entrega no detalhe do webhook para confirmar respostas 2xx.

Melhores práticas

  • Responda 200 imediatamente e processe em segundo plano. Confirme o recebimento em milissegundos e empurre o trabalho pesado para uma fila. Um endpoint lento dispara retentativas e duplicatas.
  • Seja idempotente. Trate cada entrega como "ao menos uma vez". Guarde o ID do evento/mensagem e descarte repetidos — as retentativas são normais.
  • Sempre valide a assinatura antes de confiar no payload. Nunca processe um corpo sem verificar X-Omnifox-Signature.
  • Não assuma ordem. Os eventos podem chegar fora de ordem; reordene por timestamp se a sua lógica exigir.
  • Mantenha granular. Aponte cada integração para os seus próprios eventos em vez de um webhook gigante para tudo.
  • Rotacione o segredo periodicamente pela lista de webhooks (Regenerar segredo) e atualize o seu cofre.

Se não funcionar

  • Não chegam eventos: confirme que o webhook está ativo e que a URL retorna 2xx; veja os registros de entrega.
  • Duplicatas: esperado por causa das retentativas. Implemente idempotência por ID.
  • Assinatura inválida: garanta que você assina o corpo cru (sem re-serializar o JSON) com o segredo exato.
  • Retentativas infinitas: seu endpoint está retornando 4xx/5xx ou demorando demais. Responda 200 rápido.

Dica: combine webhooks (push de eventos) com a API REST em /api/v1/* (pull sob demanda) para reconciliar o estado após uma queda do seu serviço.

Artigos relacionados

Isso foi útil?

Artigos relacionados

Fale conosco no WhatsApp