Troubleshooting: webhook sin eventos, errores de auth API y OAuth
Cómo diagnosticar webhooks que no disparan, errores 401/403 de la API REST y fallos de conexión OAuth en integraciones.
Mira este paso en el video · Solución de problemas
Nota: los conectores OAuth de la galería (Gmail, Outlook, HubSpot, Salesforce, Shopify, Google Sheets, Google Meet, Calendly, Stripe Payments, Zoom, Microsoft Teams, DocuSign, Dropbox Sign, PandaDoc y Notion) están en Próximamente: en Configuración → Integraciones su tarjeta aparece como «Próximamente» y todavía no se pueden conectar. La sección de OAuth de esta guía aplicará cuando estén disponibles. Los webhooks y la API REST sí funcionan hoy (desde el plan Crece); para conectar otras herramientas mientras tanto, usa n8n, Make o Zapier.
Para qué sirve
Esta guía resuelve los tres problemas más comunes al integrar Omnifox por API: un webhook que no recibe eventos, errores de autenticación en la API REST v1 y fallos de OAuth al conectar integraciones (Gmail, Outlook, HubSpot, etc.).
El webhook no recibe eventos
- Confirma la suscripción:
GET /v1/webhooks/{webhook}y revisa queis_activeseatruey que tu evento esté enevents. - Revisa los logs de entrega que devuelve ese mismo endpoint: si hay intentos con código de respuesta
4xx/5xx, el problema está en tu servidor (no en Omnifox). - Responde 2xx rápido: tu endpoint debe devolver
200en menos detimeout_seconds. Si tarda, Omnifox lo cuenta como fallo y reintenta hastaretry_count. - URL pública y HTTPS: la URL debe ser accesible desde Internet con certificado válido.
localhosto IPs privadas no reciben entregas. - Verifica la firma correctamente: calcula
HMAC-SHA256(body, signing_secret)y compáralo conX-Omnifox-Signature. Si rotaste el secreto (rotate-secret), actualiza el valor en tu servidor. - El evento existe: usa exactamente los nombres del catálogo (p. ej.
message.received, nomessage_received).
Errores de auth de la API (401 / 403)
- 401 Unauthorized: el token Bearer falta, está mal escrito o fue revocado. Envía
Authorization: Bearer 123_aBc...(el valor completo del token;omf_es solo el prefijo visible en la lista) y verifica la key en Configuración → API Keys. - 403 Forbidden: el token es válido pero apunta a otro workspace. Cada token está scopeado a un solo workspace; genera un token para el workspace correcto o usa el
workspace_idque corresponde. - 404 en un recurso que existe: probablemente el ID pertenece a otro workspace (el scoping lo oculta), no es que falte.
- 422 Validation error: faltan campos requeridos del body; revisa la respuesta, que lista los campos inválidos.
- 429 Too Many Requests: superaste el límite de peticiones por minuto de tu plan (p. ej. 1.200 por minuto en Crece; ver Límites de tasa (rate limits) de la API y encabezados de cuota); aplica backoff exponencial.
Fallos de OAuth al conectar integraciones (cuando estén disponibles)
- La tarjeta muestra «Próximamente»: ese conector todavía no está habilitado en Omnifox; no es un error de tu cuenta. Mientras tanto, usa n8n, Make o Zapier.
- "Selecciona un workspace antes de conectar": elige el workspace en el selector superior y reintenta.
- "La sesión OAuth expiró. Vuelve a intentarlo": el flujo tardó demasiado entre Conectar y el callback; reinícialo desde la tarjeta.
- redirect_uri_mismatch (Google/Microsoft): la URL de callback registrada en la app del proveedor no coincide con la de Omnifox. Avisa al administrador para alinear los Authorized redirect URIs.
- Se conecta pero deja de sincronizar (Gmail): el refresh token no se emitió; Desconecta y vuelve a Conectar para forzar un nuevo consentimiento.
Verificación
- Webhook: dispara un evento real (crea un contacto) y mira los logs de entrega — debe aparecer un
200. - API:
GET /v1/teamscon tu token debe responder200. - OAuth: la tarjeta de la integración debe mostrar Conectada con la cuenta.
Tips
- Loguea siempre el cuerpo crudo de cada webhook entrante: facilita comparar la firma.
- Mantén un token de API por sistema externo; así puedes revocar uno sin romper los demás.
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.