Cabeçalhos personalizados, retentativas, circuit breaker e girar a assinatura
Configure cabeçalhos sob medida, defina a política de retentativas e o circuit breaker, e gire o segredo de assinatura dos seus webhooks do Omnifox com segurança.
Veja este passo no vídeo · Segredo de assinatura, novas tentativas e cabeçalhos
Para que serve esta configuração
Depois que um webhook funciona, o próximo passo é torná-lo robusto e seguro: adicionar cabeçalhos de autenticação para o seu endpoint, controlar como o Omnifox tenta novamente em caso de falha, proteger o seu sistema com um circuit breaker e girar o segredo de assinatura quando necessário. Tudo isso é gerenciado no editor do webhook.
Como o Omnifox assina cada entrega
Em cada POST, o Omnifox inclui estes cabeçalhos:
Content-Type: application/jsonX-Omnifox-Event: o tipo de evento (ex.:message.received)X-Omnifox-Delivery-Id: identificador único da entregaX-Omnifox-Attempt: número da tentativaUser-Agent: Omnifox-Webhook/1.0X-Omnifox-Signature: sha256=<hmac>eX-Omnifox-Timestamp
A assinatura é um HMAC-SHA256 do corpo calculado com o seu segredo de assinatura. No seu servidor, recalcule o HMAC com o mesmo segredo e compare com X-Omnifox-Signature para confirmar que a requisição veio do Omnifox e não foi alterada.
Cabeçalhos personalizados
Se o seu endpoint exigir autenticação própria (um token, uma API key, etc.), adicione-a como cabeçalho:
- Abra Webhooks e clique em Editar no webhook.
- Vá até a seção Cabeçalhos personalizados e clique em Adicionar cabeçalho.
- Digite o nome (ex.:
Authorization) e o valor (ex.:Bearer meu-token). - Repita para cada cabeçalho e clique em Salvar alterações.
Esses cabeçalhos são enviados em cada entrega, além dos cabeçalhos de assinatura.
Política de retentativas
Na seção Política de retentativas você define o que acontece quando uma entrega falha:
- Estratégia:
- Exponencial (recomendada): espera crescente
2s → 4s → 8s → 16s → 32s …(máx. 5 min). - Linear: 60s entre cada tentativa.
- Sem retentativas: falha imediatamente.
- Exponencial (recomendada): espera crescente
- Máximo de retentativas: quantas tentativas adicionais são feitas (0 = nenhuma).
- Limite do circuit breaker: falhas consecutivas antes de o circuito "abrir".
O painel mostra um Cronograma de retentativas visual com o tempo de cada tentativa.
Circuit breaker
O circuit breaker protege tanto o Omnifox quanto o seu endpoint: se muitas falhas consecutivas se acumularem (o limite), o circuito fica Aberto e as entregas pausam por alguns minutos. Depois ele passa a Meio aberto e testa uma entrega: se der certo, volta a Fechado; se falhar, reabre. Isso evita sobrecarregar um servidor fora do ar. Você pode ver o estado e Forçar fechar circuit breaker na página de detalhes do webhook.
Girar o segredo de assinatura
Gire o segredo se suspeitar de vazamento ou por higiene periódica:
- Na lista de Webhooks, use o botão Regenerar segredo, ou entre em Editar e clique em Regenerar no cartão Segredo de assinatura.
- Confirme. Atenção: sua integração deixará de validar assinaturas até você atualizar o segredo no seu servidor.
- Copie o novo segredo e substitua-o no seu código pouco antes (ou logo depois) de regenerar, para minimizar a janela de falhas.
Se não funcionar
- Assinaturas inválidas após girar: seu servidor ainda usa o segredo antigo; atualize-o.
- O circuit breaker abre sozinho: seu endpoint está retornando erros; verifique o Histórico de entregas e os códigos HTTP.
- Sua API key não chega: confirme que a salvou em Cabeçalhos personalizados e clicou em Salvar alterações.
Dica: use a estratégia Exponencial com um limite de circuit breaker moderado (ex.: 10) para tolerar quedas breves sem sobrecarregar o seu sistema.
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.