El webhook o la automatización dejó de funcionar

Síntoma y contexto

Una automatización que funcionaba deja de cumplir lo prometido: el formulario se envía pero la fila no aparece en la hoja; el pedido no genera factura; el mensaje de Slack no llega; el resumen con IA deja de publicarse. A veces el fallo es ruidoso: correo de Zapier con "Zap errored", escenario de Make en rojo, nodo de n8n con error. Otras veces todo parece verde y el resultado no existe: el webhook respondió 200 pero nadie procesó el cuerpo, o el cron corrió a las 03:00 sin efecto visible.

Suele romperse tras cambios menores: renombrar un campo en el CRM, rotar una API key, actualizar un plugin que altera el JSON del webhook, migrar a HTTPS sin actualizar la URL en el panel, o alcanzar el límite de ejecuciones del plan. También cuando el origen cambia el formato del payload, caduca un token OAuth, o un modelo de OpenAI queda deprecado y la API devuelve 404.

La cadena típica tiene tres eslabones: disparador (evento, webhook, cron), transformación (Zapier, Make, n8n, script), y destino (API, base de datos, correo, LLM). Localiza primero si el flujo se ejecutó, luego qué respondió cada paso, después si el payload coincide. El historial del proveedor suele mostrar la petición HTTP, el cuerpo enviado y la respuesta del destino.

Causas probables

1. URL del webhook incorrecta, caducada o inaccesible. Apunta a entorno de prueba, falta barra final, el subdominio dejó de existir tras un deploy, o la ruta devuelve 404. Regenerar el webhook en n8n o Make crea URL nueva: la antigua deja de recibir datos.
2. Autenticación fallida o token expirado. API keys revocadas, Bearer mal pegado, OAuth sin renovar, HMAC con secreto distinto. Síntoma habitual: 401 o 403 en el paso que llama a la API externa.
3. Payload distinto al que mapea el flujo. El origen envía email y el flujo espera Email; campos anidados renombrados; valores vacíos donde el módulo siguiente exige dato obligatorio. Zapier y Make a veces fallan en silencio con campos null.
4. Cabeceras o Content-Type incorrectos. El receptor espera JSON y recibe form-urlencoded; falta Authorization; un WAF devuelve HTML en lugar de JSON. Revisa headers personalizados que el origen ya no envía.
5. Límites de cuota, rate limit o plan. OpenAI devuelve 429 al superar tokens por minuto; Zapier pausa Zaps; Make detiene escenarios; APIs gratuitas devuelven errores de billing. Un cron que dispara muchas llamadas seguidas activa throttling.
6. Error en integración LLM. Modelo incorrecto o retirado, contexto demasiado largo, parámetros no soportados en tu tier, clave sin permiso. El JSON de error de OpenAI incluye type y message con la causa (invalid_api_key, rate_limit_exceeded, context_length_exceeded).
7. Cron job o trigger temporal mal configurado. Zona horaria distinta (UTC frente a Europe/Madrid), expresión cron con typo, tarea desactivada tras reinicio, contenedor sin scheduler. Funciona a mano pero nunca se dispara solo.
8. Fallo en paso intermedio, no en el webhook entrante. El trigger recibe el evento pero falla el paso 3: filtro estricto, rama condicional que ya no se cumple, código con excepción, timeout en API lenta. El historial muestra error en un nodo concreto.
9. Cambio en el servicio origen sin actualizar el flujo. Shopify, Stripe, Typeform y otros cambian versiones de API o campos deprecados. El webhook antiguo sigue enviando pero el conector espera la versión nueva.

Checklist copiable

WEBHOOK O AUTOMATIZACIÓN ROTA - CHECKLIST

□ Nombre del flujo y proveedor (Zapier / Make / n8n / script propio / cron)
□ Qué debería ocurrir y qué ocurre (nada / error / dato incorrecto)
□ Fecha de la última ejecución correcta
□ ¿El trigger se disparó? (sí / no / no consta)
□ URL del webhook (dominio y ruta, sin token en claro)
□ Código HTTP (200, 401, 404, 422, 429, 500)
□ Mensaje de error literal del panel o del JSON
□ Payload de ejemplo con campos relevantes (censurar datos sensibles)
□ Cambios recientes (API key, deploy, plugin, campo CRM)
□ Autenticación: tipo y si se renovó recientemente
□ Content-Type y cabeceras exigidas
□ Prueba aislada (curl o Test del panel): ¿mismo resultado?
□ Límites del plan o cuota API
□ Cron: zona horaria y expresión
□ Paso exacto que falla (nombre del módulo en historial)
□ NO enviar: API keys, tokens de webhook, datos de clientes sin censurar

Qué capturar

Prepara evidencia legible en minutos, sin secretos. El objetivo es reconstruir una ejecución fallida con o sin acceso a tu cuenta.

Historial de ejecución: en Zapier, Zap History expandido; en Make, módulo en rojo con entrada y salida; en n8n, Executions con el nodo fallido; en script propio, últimas líneas del log con timestamp (sin volcar .env).

Petición y respuesta HTTP: URL (censura query con tokens), método, código de estado, cuerpo de respuesta o JSON de error. Para webhooks entrantes, indica qué sistema envía y si el receptor registró la petición.

Payload anonimizado: JSON con estructura real y valores censurados. Si el fallo es de mapeo, contrasta lo que envía el origen con lo que el conector espera.

Configuración visible: módulos implicados, filtros activos, expresión cron, zona horaria. Captura del webhook ocultando el token si la UI lo muestra.

Errores de APIs y LLM: modelo pedido, longitud aproximada del prompt, código de error literal. Indica si usas API directa, Azure OpenAI o proxy.

No envíes API keys, tokens completos ni payloads con datos personales. Acceso al panel, si hace falta, con alcance mínimo acordado por escrito.

Paneles y pruebas por herramienta

Webhook genérico

Confirma que el endpoint responde. Para POST, usa curl con el mismo Content-Type que el origen. Si hay firma HMAC (Stripe, GitHub), la prueba manual fallará sin el cálculo correcto: prioriza el log del proveedor que sí firma bien.

curl -sS -X POST "https://tu-dominio.com/ruta/webhook" \
  -H "Content-Type: application/json" \
  -d '{"evento":"prueba","id":1}'

Zapier, Make y n8n

En Zapier, revisa History, reconexión OAuth y que la URL de Catch Hook coincida con el origen. Filtros que dejan pasar cero registros parecen "flujo roto" pero son lógica de negocio.

En Make, el historial muestra el módulo en error; comprueba operaciones consumidas y que el escenario esté On. Arrays sin iterator provocan errores de tipo incompatible.

En n8n, abre Executions y el nodo fallido. Si es self-hosted, confirma que el proceso sigue tras reinicio y que la URL pública no cambió.

Cron y OpenAI

Para cron jobs, revisa crontab -l, rutas absolutas al script y variables de entorno (cron no carga tu .bashrc). Redirige stderr a log para no perder errores.

Para OpenAI, lee el JSON completo del error: clave inválida, modelo mal escrito, exceso de tokens, rate limit. Prueba con prompt mínimo y modelo estable para aislar volumen frente a contenido.

Cuándo escalar

Puedes seguir solo cuando el fallo es reversible: URL mal pegada, OAuth por reconectar, filtro que excluye registros, cron con zona horaria equivocada, API key caducada en variables de entorno. Lanza ejecución manual antes de confiar en el trigger automático.

Conviene escalar cuando:

• El paso que llama a tu API o base de datos devuelve 500 y no tienes logs del servidor destino.
• El webhook no aparece en logs del receptor y sospechas firewall, WAF o Cloudflare bloqueando POST externos.
• Varios conectores fallan tras un cambio en el servicio origen y la migración de versión no está clara.
• La integración LLM falla por cuota o billing y necesitas ajustar el flujo sin cortar producción.
• El flujo es crítico (pedidos, facturación, alertas) y cada hora sin disparo tiene impacto directo.
• Tras rotar credenciales en todos los módulos visibles, sigue habiendo 401 o firmas inválidas.

Al escribir por el formulario, elige Automatización o IA, incluye la checklist marcada, capturas del historial, código de error y payload sin secretos. Con eso suele bastar para señalar el módulo roto o indicar qué log abrir a continuación.