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.
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
- Entra a Configuración → Webhooks y toca Nuevo webhook.
- Pega la URL de destino (siempre HTTPS).
- 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. - Copia y guarda el secreto de firma (
whsec_…) en tu vault. Omnifox firma cada envío con él. - Configura la estrategia de reintentos (
exponencialrecomendado) y el máximo de reintentos (por defecto 5). - 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
Artículos relacionados
-
Cómo conectar integraciones y apps externas
Conecta Omnifox con tus herramientas favoritas desde el catálogo de integraciones en pocos pasos.
-
Guía completa de integraciones y API
Integraciones y API a fondo, en 30 capítulos: claves API, llamadas reales, webhooks firmados, n8n, MCP y SDK, todo funcionando de verdad.
-
Integrar Omnifox con Azur, Siigo, Alegra, QuickBooks u otro sistema contable o ERP
Omnifox no tiene hoy un conector nativo con sistemas contables o ERP. Te explicamos cómo conectarlos igual con workflows, el nodo HTTP, n8n, Make, Zapier o la API, con ejemplos.
-
Generar y usar API keys y webhooks
Crea claves de API para acceder a Omnifox por código y configura webhooks para recibir eventos en tiempo real.
-
Introducción a las integraciones (webhook / OAuth / API key)
Conecta Omnifox con tus otras herramientas: qué está disponible hoy, qué llega pronto y cuándo usar un webhook, una conexión OAuth o una clave de API.