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.

Jun 26, 2026

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/json
  • X-Omnifox-Event: o tipo de evento (ex.: message.received)
  • X-Omnifox-Delivery-Id: identificador único da entrega
  • X-Omnifox-Attempt: número da tentativa
  • User-Agent: Omnifox-Webhook/1.0
  • X-Omnifox-Signature: sha256=<hmac> e X-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:

  1. Abra Webhooks e clique em Editar no webhook.
  2. Vá até a seção Cabeçalhos personalizados e clique em Adicionar cabeçalho.
  3. Digite o nome (ex.: Authorization) e o valor (ex.: Bearer meu-token).
  4. 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.
  • 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:

  1. Na lista de Webhooks, use o botão Regenerar segredo, ou entre em Editar e clique em Regenerar no cartão Segredo de assinatura.
  2. Confirme. Atenção: sua integração deixará de validar assinaturas até você atualizar o segredo no seu servidor.
  3. 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

Isso foi útil?

Artigos relacionados

Fale conosco no WhatsApp