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.
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
- Acesse Configurações → Webhooks e clique em Novo webhook.
- Cole a URL de destino (sempre HTTPS).
- Escolha os eventos que precisa:
message.received,message.sent,conversation.created,conversation.closed,contact.created,contact.updated. Assine apenas o que for usar. - Copie e guarde o segredo de assinatura (
whsec_…) no seu cofre. O Omnifox assina cada envio com ele. - Configure a estratégia de retentativas (
exponencialrecomendado) e o máximo de retentativas (padrão 5). - 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
Artigos relacionados
-
Como conectar integrações e apps externos
Conecte o Omnifox às suas ferramentas favoritas a partir do catálogo de integrações em poucos passos.
-
Integrar o Omnifox com Azur, Siigo, Alegra, QuickBooks ou outro sistema contábil ou ERP
O Omnifox não tem hoje um conector nativo com sistemas contábeis ou ERP. Veja como fazer essa conexão mesmo assim com fluxos de trabalho, o nó HTTP, n8n, Make, Zapier ou a API, com exemplos.
-
Guia completo de integrações e API
Integrações e API a fundo, em 30 capítulos: chaves de API, chamadas reais, webhooks assinados, n8n, MCP e SDKs, tudo funcionando de verdade.
-
Gerar e usar API keys e webhooks
Crie chaves de API para acessar o Omnifox por código e configure webhooks para receber eventos em tempo real.
-
Introdução às integrações (webhook / OAuth / chave de API)
Conecte o Omnifox às suas outras ferramentas: o que está disponível hoje, o que chega em breve e quando usar um webhook, uma conexão OAuth ou uma chave de API.