Mejores prácticas: webhooks confiables e integraciones escalables

Cómo construir webhooks que no pierden ni duplican eventos: firma HMAC, idempotencia, reintentos y respuesta rápida.

Jun 26, 2026

Mira este paso en el video · Buenas prácticas de seguridad

¿Para qué sirve?

Los webhooks de Omnifox empujan eventos en tiempo real (mensajes, conversaciones y contactos) a tu propio sistema, sin que tengas que consultar la API constantemente. Bien construidos, son la columna de una integración escalable; mal construidos, pierden eventos o duplican datos. Esta guía reúne las prácticas que recomendamos para producción.

Requisitos

  • Rol con acceso a Configuración → Webhooks (acceso a la API de desarrollador).
  • Un endpoint HTTPS público que responda rápido (idealmente < 5 s).
  • Capacidad de validar firmas HMAC-SHA256 en tu backend.

Pasos

  1. Entra a Configuración → Webhooks y toca Nuevo webhook.
  2. Pega la URL de destino (siempre HTTPS).
  3. Elige los eventos que necesitas: message.received, message.sent, conversation.created, conversation.closed, contact.created, contact.updated. Suscríbete solo a lo que vas a usar.
  4. Copia y guarda el secreto de firma (whsec_…) en tu vault. Omnifox firma cada envío con él.
  5. Configura la estrategia de reintentos (exponencial recomendado) y el máximo de reintentos (por defecto 5).
  6. Guarda y usa Enviar prueba para disparar un test.ping.

Verificación

Omnifox firma el cuerpo con HMAC-SHA256 y lo envía en la cabecera X-Omnifox-Signature; el tipo de evento viaja en X-Omnifox-Event. En tu endpoint, recalcula el HMAC del cuerpo crudo con tu secreto y compara en tiempo constante. Si no coincide, devuelve 401. Revisa los registros de entrega en el detalle del webhook para confirmar respuestas 2xx.

Mejores prácticas

  • Responde 200 de inmediato y procesa en segundo plano. Acusa recibo en milisegundos y empuja el trabajo pesado a una cola. Un endpoint lento dispara reintentos y duplicados.
  • Sé idempotente. Trata cada entrega como "al menos una vez". Guarda el ID del evento/mensaje y descarta repetidos: los reintentos son normales.
  • Valida siempre la firma antes de confiar en el payload. Nunca proceses un cuerpo sin verificar X-Omnifox-Signature.
  • No bloquees por orden. Los eventos pueden llegar desordenados; reordena por timestamp si tu lógica lo exige.
  • Granularidad mínima. Suscribe cada integración a sus propios eventos en lugar de un webhook gigante "para todo".
  • Rota el secreto periódicamente desde la lista de webhooks (Regenerar secreto) y actualiza tu vault.

Si no funciona

  • No llegan eventos: confirma que el webhook esté activo y que la URL responda 2xx; mira los registros de entrega.
  • Llegan duplicados: es esperado por los reintentos. Implementa idempotencia por ID.
  • Firma inválida: asegúrate de firmar el cuerpo crudo (sin re-serializar el JSON) con el secreto exacto.
  • Reintentos infinitos: tu endpoint está devolviendo 4xx/5xx o tarda demasiado. Responde 200 rápido.

Tip: combina webhooks (push de eventos) con la API REST en /api/v1/* (pull bajo demanda) para reconciliar estado tras una caída de tu servicio.

Artículos relacionados

¿Te fue útil?

Artículos relacionados

Escríbenos por WhatsApp