Headers personalizados, reintentos, circuit breaker y rotar firma

Configura cabeceras a medida, define la política de reintentos y el circuit breaker, y rota el secreto de firma de tus webhooks de Omnifox de forma segura.

Jun 26, 2026

Mira este paso en el video · Secreto de firma, reintentos y encabezados

Para qué sirve esta configuración

Cuando un webhook ya funciona, el siguiente paso es hacerlo robusto y seguro: añadir cabeceras de autenticación para tu endpoint, controlar cómo Omnifox reintenta ante fallos, proteger tu sistema con un circuit breaker y rotar el secreto de firma cuando sea necesario. Todo esto se gestiona desde el editor del webhook.

Cómo Omnifox firma cada entrega

En cada POST, Omnifox incluye estas cabeceras:

  • Content-Type: application/json
  • X-Omnifox-Event: el tipo de evento (p. ej. message.received)
  • X-Omnifox-Delivery-Id: identificador único de la entrega
  • X-Omnifox-Attempt: número de intento
  • User-Agent: Omnifox-Webhook/1.0
  • X-Omnifox-Signature: sha256=<hmac> y X-Omnifox-Timestamp

La firma es un HMAC-SHA256 del cuerpo calculado con tu secreto de firma. En tu servidor, recalcula el HMAC con el mismo secreto y compáralo con X-Omnifox-Signature para confirmar que la petición vino de Omnifox y no fue alterada.

Headers personalizados

Si tu endpoint exige autenticación propia (un token, una API key, etc.), añádela como cabecera:

  1. Abre Webhooks y entra a Editar en el webhook.
  2. Baja a la sección Headers personalizados y pulsa Añadir cabecera.
  3. Escribe el nombre (p. ej. Authorization) y el valor (p. ej. Bearer mi-token).
  4. Repite por cada cabecera y pulsa Guardar cambios.

Estas cabeceras se envían en cada entrega además de las de firma.

Política de reintentos

En la sección Política de reintentos defines qué pasa cuando una entrega falla:

  • Estrategia:
    • Exponencial (recomendada): espera creciente 2 s → 4 s → 8 s → 16 s → 32 s … (máx. 5 min).
    • Lineal: 60 s entre cada intento.
    • Sin reintentos: falla de inmediato.
  • Máximo de reintentos: cuántos intentos adicionales se hacen (0 = ninguno).
  • Umbral del circuit breaker: fallos consecutivos antes de "abrir" el circuito.

El panel muestra un Calendario de reintentos visual con los tiempos de cada intento.

Circuit breaker

El circuit breaker protege tanto a Omnifox como a tu endpoint: si se acumulan demasiados fallos consecutivos (el umbral), el circuito pasa a Abierto y se dejan de enviar entregas durante unos minutos. Luego pasa a Medio abierto y prueba una entrega: si tiene éxito, vuelve a Cerrado; si falla, se reabre. Esto evita martillar un servidor caído. Puedes ver el estado y Forzar cerrar circuit breaker desde el detalle del webhook.

Rotar el secreto de firma

Rota el secreto si sospechas que se filtró o por higiene periódica:

  1. En la lista de Webhooks, usa el botón Regenerar secreto, o entra a Editar y pulsa Regenerar en la tarjeta Secreto de firma.
  2. Confirma. Atención: tu integración dejará de validar firmas hasta que actualices el secreto en tu servidor.
  3. Copia el nuevo secreto y reemplázalo en tu código antes (o justo después) de regenerar para minimizar la ventana de fallos.

Si no funciona

  • Firmas inválidas tras rotar: tu servidor sigue usando el secreto viejo; actualízalo.
  • El circuit breaker se abre solo: tu endpoint devuelve errores; revisa el Historial de entregas y los códigos HTTP.
  • Tu API key no llega: confirma que la guardaste en Headers personalizados y pulsaste Guardar cambios.

Tip: usa la estrategia Exponencial con un umbral de circuit breaker moderado (p. ej. 10) para tolerar caídas breves sin saturar tu sistema.

Artículos relacionados

¿Te fue útil?

Artículos relacionados

Escríbenos por WhatsApp