Cómo configurar webhooks de mensajería de Zendesk: Una guía completa

Los webhooks convierten su Zendesk en un motor de notificaciones en tiempo real. En lugar de verificar manualmente las actualizaciones, los webhooks envían datos a sistemas externos en el momento en que sucede algo, ya sea que se cree un ticket, llegue un mensaje o un usuario actualice su perfil.

Las aplicaciones prácticas van desde alertas de Slack para tickets urgentes hasta alimentar herramientas de IA como eesel AI con datos de clientes en vivo. Esta guía recorre ambos tipos de webhooks de Zendesk (basados en eventos y basados en disparadores), cubre la configuración específica de mensajería a través de la API de Conversaciones y explica los métodos de autenticación para que sus integraciones se mantengan seguras.

Al final, tendrá webhooks funcionales conectados a sus flujos de trabajo de soporte.

¿Qué son los webhooks de Zendesk y cómo funcionan?

Un webhook envía una solicitud HTTP a una URL específica cada vez que sucede algo en Zendesk Support, Guide, Gather o Messaging. Piense en ello como una notificación push en tiempo real para sus sistemas. Cuando se elimina un usuario o llega un nuevo ticket, Zendesk notifica a su punto final (endpoint) con los datos relevantes.

Los casos de uso comunes incluyen:

• Alertas de Slack o Teams para tickets de alta prioridad
• Sincronización de CRM para mantener actualizados los registros de los clientes
• Notificaciones por SMS a través de servicios como Twilio o 8x8
• Integraciones de IA donde las herramientas procesan mensajes entrantes y generan respuestas

Dos métodos de conexión de webhooks

Esta distinción es importante porque no se pueden mezclar. Una vez que crea un webhook con un método, no puede cambiarlo.

Webhooks suscritos a eventos: responden a eventos de Zendesk como la creación de usuarios, actualizaciones de organizaciones, publicación de artículos del centro de ayuda o actividad de mensajería. Estos siempre utilizan POST con una carga útil (payload) JSON, y Zendesk controla la estructura de dicha carga.

Webhooks de disparador o automatización: se conectan a sus reglas de negocio de Support. Cuando un ticket cumple ciertas condiciones, el webhook se activa. Usted obtiene el control total sobre el método HTTP (GET, POST, PUT, PATCH, DELETE) y puede personalizar el formato de la solicitud (JSON, XML o codificado por formulario). La carga útil utiliza marcadores de posición como {{ticket.id}} que Zendesk completa en tiempo de ejecución.

Tipo de conexión	Activado por	Métodos HTTP	Control de carga útil
Eventos de Zendesk	Actividad de usuario, org, mensajería, centro de ayuda	Solo POST	Definido por Zendesk
Disparador/Automatización	Condiciones del ticket	Todos los métodos	Definido por el usuario con marcadores

Cómo configurar webhooks de Zendesk para mensajería y disparadores

La configuración de webhooks requiere acceso de administrador o un rol personalizado con permisos de webhook. Aquí está el proceso paso a paso.

Paso 1: Acceda a la sección de webhooks en el Centro de administración

Navegue al Centro de administración, luego haga clic en Aplicaciones e integraciones en la barra lateral. Seleccione Webhooks en el submenú. Verá una lista de webhooks existentes (si los hay) y un botón para crear nuevos.

Las cuentas de prueba tienen límites: un máximo de 10 webhooks y 60 invocaciones por minuto. Los planes de pago eliminan estas restricciones.

Paso 2: Cree un nuevo webhook

Haga clic en "Crear webhook" y elija su método de conexión:

• Eventos de Zendesk: seleccione esto para actividad de mensajería, usuario, organización o centro de ayuda. Elegirá eventos específicos para suscribirse.
• Disparador o Automatización: seleccione esto para actividad basada en tickets donde desee cargas útiles personalizadas.

La elección aquí es permanente. No puede convertir un webhook de disparador en uno suscrito a eventos más adelante, así que elija el correcto desde el principio.

Paso 3: Configure los ajustes del webhook

Complete la configuración básica:

• Nombre y descripción: use nombres descriptivos como "Alertas de Slack para tickets urgentes" o "Sincronización de clientes CRM" para que su equipo sepa qué hace cada webhook.
• URL del punto final (endpoint): la URL de su servidor receptor. Se recomienda encarecidamente HTTPS por seguridad.
• Método de solicitud: para webhooks suscritos a eventos, siempre es POST. Para webhooks de disparador, elija según lo que espere su punto final.
• Formato de solicitud: JSON, XML o codificado por formulario (solo webhooks de disparador).

También puede agregar hasta 5 encabezados personalizados para puntos finales HTTPS. Los nombres de los encabezados admiten caracteres alfanuméricos y algunos símbolos, con un límite de 128 caracteres. Los valores pueden tener hasta 1,000 caracteres.

Paso 4: Configure la autenticación

Elija el método de autenticación que requiera su punto final:

Método	Cuándo usarlo	Configuración
Ninguno	Pruebas o puntos finales con lista de permitidos de IP	No se necesitan credenciales
Clave de API	Servicios de terceros con autenticación de encabezado	Par nombre/valor en el encabezado
Autenticación básica	Servicios internos o llamadas a la API de Zendesk	Usuario y contraseña (use el formato {email}/token:{api_token} para Zendesk)
Token de portador (Bearer)	Servicios habilitados para OAuth	Token de acceso en el encabezado de Autorización

Todos los métodos de autenticación deben usar HTTPS. Nunca coloque credenciales sensibles en encabezados personalizados; use las opciones de autenticación integradas en su lugar.

Paso 5: Conecte a un disparador o automatización

Para los webhooks basados en disparadores, debe conectarlos a una regla de negocio:

1. Vaya al Centro de administración, luego a Objetos y reglas, luego a Reglas de negocio y finalmente a Disparadores.
2. Cree un nuevo disparador o edite uno existente.
3. En Acciones, haga clic en "Agregar acción".
4. Seleccione "Notificar webhook" y elija su webhook del menú desplegable.
5. Defina la carga útil JSON usando marcadores de posición. Por ejemplo:

{
  "ticket_id": "{{ticket.id}}",
  "subject": "{{ticket.title}}",
  "status": "{{ticket.status}}",
  "requester_email": "{{ticket.requester.email}}"
}

Zendesk reemplaza estos marcadores con valores reales antes de enviar la solicitud. La carga útil debe ser inferior a 256 KB.

Paso 6: Pruebe su webhook

Antes de activarlo, use la función de prueba integrada:

1. Abra su webhook desde la página de Webhooks.
2. Haga clic en "Probar webhook".
3. Seleccione un evento de muestra o ingrese datos de prueba.
4. Haga clic en "Enviar prueba" y verifique la respuesta.

Un código de estado 200 significa éxito. Si obtiene errores, verifique los registros de su punto final. Los problemas comunes incluyen URLs incorrectas, autenticación inválida o cargas útiles mal formadas.

Para el desarrollo local, herramientas como ngrok o Hookdeck crean URLs públicas que se conectan a su servidor local. Esto le permite probar webhooks sin desplegarlos en producción.

Configuración de webhooks de mensajería de Zendesk con la API de Conversaciones

La plataforma de mensajería de Zendesk (Sunshine Conversations) tiene su propio sistema de webhooks para mensajería en tiempo real. Este es independiente de los webhooks estándar y está diseñado específicamente para interacciones de chat.

Creación de un webhook de mensajería

Los webhooks de mensajería pertenecen a una integración. Puede crear uno a través del Centro de administración o la API:

1. Cree una integración personalizada en el Centro de administración bajo Aplicaciones e integraciones.
2. Registre la URL de destino de su webhook.
3. Configure qué eventos recibir (como conversation:message).
4. Establezca opciones adicionales como includeFullUser e includeFullSource para obtener cargas útiles más detalladas.

Eventos clave de webhook para mensajería

La plataforma de mensajería admite varios tipos de eventos:

Evento	Descripción
conversation:message	Cualquier mensaje enviado por el usuario o la empresa
conversation:read	El usuario leyó los mensajes
conversation:postback	El usuario hizo clic en un botón de postback
passthrough:messaging	Datos de paso (passthrough) específicos del canal

Comprensión de la carga útil del webhook

Cuando llega un mensaje, la carga útil del webhook incluye todo lo que necesita para responder adecuadamente:

{
  "account_id": 21825834,
  "detail": {
    "id": "141"
  },
  "event": {
    "actor": {
      "id": "zd:answerBot",
      "name": "Support Bot",
      "type": "system"
    },
    "conversation_id": "67ab5f53a96f98663935c3f2",
    "message": {
      "body": "Hola. ¿Cómo puedo ayudarte hoy?",
      "id": "67ab5f55155becd183e284cb"
    }
  },
  "type": "zen:event-type:messaging_ticket.message_added"
}

Los campos clave incluyen el ID de la conversación (para rastrear el hilo), el contenido del mensaje y la información del actor (si el mensaje provino de un usuario, agente o sistema). Estos datos permiten que las herramientas de IA analicen los mensajes entrantes y generen respuestas contextuales automáticamente.

Métodos de autenticación y mejores prácticas de seguridad para la configuración de webhooks de mensajería de Zendesk

La seguridad es importante. Un punto final de webhook no asegurado puede filtrar datos de clientes o permitir que actores malintencionados inyecten solicitudes falsas.

Elección del método de autenticación adecuado

Método	Ideal para	Notas
Clave de API	Servicios de terceros	Autenticación simple basada en encabezados
Autenticación básica	Servicios internos, llamadas a la API de Zendesk	Use el formato {email}/token:{token}
Token de portador (Bearer)	Servicios habilitados para OAuth	Estándar para APIs modernas
Ninguno	Solo pruebas	Nunca lo use en producción

Verificación de firmas de webhook

Para integraciones críticas de seguridad, Zendesk proporciona verificación de firma. Cada solicitud incluye dos encabezados:

• X-Zendesk-Webhook-Signature: La firma principal
• X-Zendesk-Webhook-Signature-Timestamp: Marca de tiempo para la verificación

Para verificar:

1. Extraiga ambos encabezados de la solicitud entrante.
2. Concatene la marca de tiempo y el cuerpo de la solicitud.
3. Cree un hash HMAC SHA256 usando el secreto de firma de su webhook.
4. Codifique el resultado en Base64.
5. Compárelo con el encabezado de la firma.

El algoritmo se ve así: base64(HMACSHA256(TIMESTAMP + CUERPO))

Si las firmas coinciden, la solicitud es genuina. Si no, rechácela.

Puede encontrar su secreto de firma en el Centro de administración bajo la configuración de su webhook (haga clic en "Revelar secreto"). Para realizar pruebas antes de la creación del webhook, use el secreto de prueba estático: dGhpc19zZWNyZXRfaXNfZm9yX3Rlc3Rpbmdfb25seQ==

Recomendaciones de seguridad

• Use siempre puntos finales HTTPS
• Implemente la verificación de firma para webhooks de producción
• Haga que los controladores de webhook sean idempotentes (Zendesk puede reintentar o enviar duplicados)
• Supervise los registros de actividad de webhooks para entregas fallidas
• Use gestión de secretos, no credenciales integradas en el código

Resolución de problemas comunes en la configuración de webhooks de mensajería de Zendesk

Incluso los webhooks bien configurados pueden fallar. Aquí se explica cómo diagnosticar y solucionar los problemas más comunes.

Errores de conexión

Error	Causa	Solución
401/403	Credenciales inválidas	Verifique la clave de API o el token, compruebe que el método de autenticación coincida con lo que espera el punto final
404	URL de punto final incorrecta	Confirme que la ruta de la URL y el dominio sean correctos
Tiempo de espera (Timeout)	Punto final demasiado lento	Responda en menos de 12 segundos, procese los datos de forma asíncrona
Error de SSL	Problema de certificado	Use un certificado válido firmado por una CA (Let's Encrypt funciona bien)

Activación del disyuntor (circuit breaker)

Zendesk protege los puntos finales para que no se vean abrumados. El disyuntor se activa cuando:

• El 70% de las solicitudes fallan en 5 minutos, O
• Ocurren más de 1,000 errores en 5 minutos

Cuando se activa, los webhooks se pausan durante 5 segundos. Después de la pausa, Zendesk lo intenta de nuevo. Una solicitud exitosa restablece el circuito; un fallo activa otra pausa de 5 segundos. Este ciclo continúa hasta que su punto final se recupera.

El disyuntor no se activará si ocurren menos de 100 solicitudes en 5 minutos, por lo que los webhooks de bajo volumen generalmente están a salvo de bloqueos accidentales.

Consejos de depuración

• Verifique el Centro de administración en Webhooks para ver los registros de actividad (se conservan durante 7 días)
• Filtre los registros por estado: filter[status]=failed
• Use herramientas de monitoreo de solicitudes para inspeccionar las cargas útiles reales
• Verifique que el formato de la carga útil coincida con lo que espera su punto final
• Pruebe con herramientas como Postman o curl para aislar problemas

Comportamiento de reintento

Respuesta	Comportamiento
HTTP 409	Reintenta hasta 3 veces
HTTP 429/503 con retry-after < 60s	Reintenta según el encabezado
Tiempo de espera (>12 segundos)	Reintenta hasta 5 veces
Otros errores	Sin reintento automático

Zendesk hace el mejor esfuerzo para entregar los webhooks una vez, pero es posible que ocurran duplicados o eventos perdidos. Diseñe sus controladores para que sean idempotentes.

Optimice las integraciones de webhooks con eesel AI

Configurar webhooks es solo el primer paso. Construir respuestas inteligentes requiere desarrollo adicional: analizar cargas útiles, integrar con su base de conocimientos, elaborar respuestas contextuales y manejar casos excepcionales. Ahí es donde entramos nosotros.

eesel AI se conecta a su Zendesk y maneja la complejidad por usted:

• Procesamiento en tiempo real: Ingerimos eventos de tickets y mensajería a medida que ocurren; no se requiere desarrollo de webhooks por su parte.
• Respuestas contextuales: Nuestra IA utiliza su base de conocimientos, tickets pasados y centro de ayuda para generar respuestas que coincidan con la voz de su marca.
• Acciones más allá de las respuestas: Busque pedidos en Shopify, procese reembolsos, actualice campos de tickets y más, todo configurado sin código.
• Despliegue gradual: Comience con el modo copiloto (borrador para revisión) antes de pasar a las respuestas autónomas.

Cómo empezar con eesel AI para Zendesk

La configuración toma minutos:

1. Conecte su cuenta de Zendesk a través de nuestro panel.
2. Entrene con sus datos existentes (tickets pasados, artículos del centro de ayuda, macros, documentos conectados).
3. Elija su modo: copiloto (los agentes revisan los borradores de la IA) o autónomo (la IA responde directamente).
4. Realice simulaciones en tickets pasados para verificar la calidad antes de activarlo.

Esto elimina la necesidad de construir controladores de webhook personalizados mientras ofrece automatización de soporte impulsada por IA. Los despliegues maduros logran hasta un 81% de resolución autónoma con períodos de recuperación de la inversión inferiores a 2 meses.

Plan	Mensual	Anual	Interacciones/mes
Team	$299	$239/mes	1,000
Business	$799	$639/mes	3,000
Custom	Contáctenos	Personalizado	Ilimitado

El plan Business incluye Agente de IA para respuestas autónomas, entrenamiento con tickets pasados y capacidades de simulación masiva. Pruebe eesel AI gratis durante 7 días.