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.

Jun 26, 2026

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

  1. Confirma la suscripción: GET /v1/webhooks/{webhook} y revisa que is_active sea true y que tu evento esté en events.
  2. 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).
  3. Responde 2xx rápido: tu endpoint debe devolver 200 en menos de timeout_seconds. Si tarda, Omnifox lo cuenta como fallo y reintenta hasta retry_count.
  4. URL pública y HTTPS: la URL debe ser accesible desde Internet con certificado válido. localhost o IPs privadas no reciben entregas.
  5. Verifica la firma correctamente: calcula HMAC-SHA256(body, signing_secret) y compáralo con X-Omnifox-Signature. Si rotaste el secreto (rotate-secret), actualiza el valor en tu servidor.
  6. El evento existe: usa exactamente los nombres del catálogo (p. ej. message.received, no message_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_id que 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/teams con tu token debe responder 200.
  • 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

¿Te fue útil?

Artículos relacionados

Escríbenos por WhatsApp