Integración de n8n con Zendesk: nodos, credenciales y workflows de ejemplo

El nodo Zendesk lee o modifica datos en Zendesk como un paso más de un workflow. La documentación de n8n agrupa sus operaciones por recurso.

Hay un comportamiento que pilla a muchos por sorpresa. Cuando usas 'Update Ticket' y rellenas el campo 'Tag Names or IDs', la documentación de n8n indica que se sustituye toda la lista de etiquetas del ticket, así que cualquier etiqueta que no incluyas se elimina. Esto sigue el comportamiento predeterminado de la API de Zendesk con las actualizaciones de etiquetas. La documentación propone tres soluciones: obtener las etiquetas actuales y combinarlas con las nuevas antes de actualizar, usar el nodo HTTP Request con la propiedad additional_tags de Zendesk o llamar al endpoint de etiquetas del ticket. Las dos últimas añaden etiquetas sin eliminar las existentes.

Si el nodo no admite una operación que necesitas, usa el nodo HTTP Request, pon 'Authentication' en 'Predefined Credential Type' y elige tu credencial de Zendesk. La solicitud reutiliza entonces la misma conexión que el nodo Zendesk.

Los nodos Zendesk y Zendesk Trigger usan la misma credencial, y n8n admite dos formas de autenticarse. Ambas necesitan tu subdominio, que es la parte de la URL de Zendesk entre https:// y .zendesk.com.

• Token de API: en Zendesk Admin Center, abre 'Apps and integrations' y luego 'APIs', y activa el acceso por token para la API de Zendesk. Añade un token con una descripción y cópialo. En n8n, introduce el subdominio, la dirección de correo con la que inicias sesión en Zendesk y el token.
• OAuth2: en Zendesk Admin Center, crea un cliente OAuth en 'Apps and integrations' y luego 'APIs'. Pega la URL de callback de OAuth de n8n en el campo de URL de redirección del cliente. Copia el identificador único del cliente en 'Client ID' en n8n y su secreto en 'Client Secret', añade el subdominio, guarda y conecta tu cuenta de Zendesk.

Hay dos formas de iniciar un workflow de n8n desde Zendesk. El nodo Zendesk Trigger inicia un workflow cuando los eventos de Zendesk cumplen las condiciones que defines en el nodo. En el ejemplo de la documentación de n8n, filtra los tickets cuyo estado es 'Open', y el workflow se ejecuta en cuanto lo activas.

La alternativa es construir la conexión tú mismo. En Zendesk Admin Center, ve a 'Apps and integrations' y luego a 'Webhooks', crea un webhook, elige 'Trigger or Automation' como método de conexión y apúntalo a la 'Production URL' de un nodo Webhook de n8n. Después, añade la acción 'Notify webhook' a un trigger o una automatización de Zendesk y escribe el payload, que no puede superar los 16.000 caracteres. Así las condiciones se quedan en las reglas de negocio de Zendesk y puedes elegir exactamente qué campos enviar.

Si usas un webhook, comprueba que las solicitudes vienen de verdad de Zendesk. Zendesk envía dos cabeceras, X-Zendesk-Webhook-Signature y X-Zendesk-Webhook-Signature-Timestamp. La firma es base64(HMACSHA256(timestamp + body)) generada con el secreto de firma del webhook, que puedes mostrar en la página de detalles del webhook u obtener a través de la API. Vuelve a calcularla en tu workflow y rechaza las solicitudes que no coincidan. Zendesk también indica que la misma acción puede llamar a un webhook más de una vez, así que haz que el workflow pueda ejecutarse dos veces para el mismo ticket sin problemas.

El nodo Webhook puede responder de inmediato, cuando termina el último nodo o mediante un nodo Respond to Webhook aparte. En los workflows más largos, responder de inmediato da a Zendesk una respuesta rápida mientras el resto del trabajo continúa.

Este es un patrón habitual, descrito paso a paso. Muestra cómo encajan los nodos. No es un caso de éxito de TascaLab.

1. Trigger: un nodo Zendesk Trigger, o un nodo Webhook alimentado por un trigger de Zendesk que se activa cuando se crea un ticket. Envía al menos el ID del ticket.
2. Obtener: un nodo Zendesk con el recurso Ticket obtiene el ticket completo, incluidos el asunto, la descripción y las etiquetas actuales.
3. Clasificar: un nodo Text Classifier clasifica el texto en categorías que defines, como facturación, incidencia técnica o reembolso. Cada categoría tiene un nombre y una descripción que ayuda al modelo. Por defecto, los elementos que no coinciden con ninguna categoría se descartan, así que activa la rama 'Other' para recogerlos.
4. Actualizar: un nodo Zendesk fija el grupo y las etiquetas. Combina primero las etiquetas existentes, o añade etiquetas mediante el nodo HTTP Request con additional_tags, para no borrar las etiquetas que hayan puesto los agentes.
5. Avisar: un nodo Slack publica la categoría y un enlace al ticket en el canal del equipo.
6. Gestionar errores: envía las ejecuciones fallidas a una alerta, y espera y reintenta cuando Zendesk devuelva una respuesta 429.

Puedes ampliar el mismo patrón. Envía los tickets urgentes a un canal de Slack aparte, o consulta la organización del cliente con el recurso Organization antes de elegir un grupo.

Zendesk limita las solicitudes a la API por minuto según el plan. Su documentación para desarrolladores indica estos límites predeterminados para las APIs de Support y Help Center:

• Suite Team: 200 solicitudes por minuto.
• Suite Growth y Suite Professional: 400 solicitudes por minuto.
• Suite Enterprise: 700 solicitudes por minuto.
• Suite Enterprise Plus: 2.500 solicitudes por minuto.

El complemento High Volume API sube un plan que cumpla los requisitos a 2.500 solicitudes por minuto. Sustituye el límite del plan en lugar de sumarse a él, y requiere Suite Growth o superior (o Support Professional o superior) con al menos 10 licencias de agente. Por encima del límite, Zendesk devuelve HTTP 429 con una cabecera Retry-After que indica cuántos segundos esperar. Algunos endpoints tienen sus propios límites, más estrictos. Cuenta las llamadas a la API que hace cada ejecución y multiplícalas por tu volumen máximo de tickets. Los trabajos masivos, como añadir etiquetas a tickets antiguos, tienen más probabilidades de alcanzar el límite, así que divídelos en lotes y añade esperas.

n8n funciona como n8n Cloud, una instancia gestionada que n8n opera por ti, o autoalojado en tu propia máquina o infraestructura. Para la mayoría de las instalaciones autoalojadas, la documentación recomienda Docker, y recomienda n8n Cloud si no tienes experiencia gestionando servidores. Con cualquiera de los dos métodos de activación, Zendesk tiene que poder llegar a tu instancia de n8n. Si una instancia autoalojada está detrás de un proxy inverso, define N8N_WEBHOOK_URL con su URL base pública para que n8n muestre las URL de webhook correctas y los servicios externos las registren correctamente. N8N_WEBHOOK_URL sustituye a WEBHOOK_URL, que sigue funcionando pero está obsoleta desde n8n 2.35.0.

TascaLab crea automatizaciones de Zendesk como esta con n8n, Make, APIs y webhooks, sobre las herramientas que ya usas. Los proyectos de Ticket Routing & Categorization cuestan 690 €, y los de Custom Automation, desde 1070 €. La mayoría de las implementaciones llevan de 1 a 3 semanas, y todos los proyectos incluyen documentación básica y 30 días de soporte tras el lanzamiento. Puedes empezar con una llamada de Health Check gratuita de 30 minutos.