Webhook de conversación creada en Zendesk Messaging: Una guía completa de implementación

Las notificaciones en tiempo real son la columna vertebral de los flujos de trabajo de soporte modernos. Cuando un cliente inicia una conversación, sus sistemas deben saberlo inmediatamente, no cuando alguien comprueba manualmente si hay actualizaciones. Los webhooks llenan este vacío.

Pero aquí está la cuestión con Zendesk: tienen dos sistemas de webhook completamente diferentes, y el webhook "conversación creada" funciona de manera diferente a lo que la mayoría de la gente espera. Esta guía elimina la confusión y le muestra exactamente cómo configurar y utilizar los webhooks de conversación en Zendesk, ya sea que esté construyendo integraciones de IA, sincronizando datos con su CRM o enrutando notificaciones a Slack.

¿Qué es el webhook de conversación creada en Zendesk Messaging?

Aclaremos primero una idea errónea común. Cuando la gente busca "webhook de conversación creada en Zendesk Messaging", normalmente están pensando en la plataforma de mensajería Sunshine Conversations (la infraestructura que impulsa Zendesk Messaging). Pero el evento real de "conversación creada" vive en un sistema diferente por completo.

Zendesk tiene dos arquitecturas de webhook:

Los Webhooks estándar de Zendesk manejan tickets, usuarios, organizaciones y sí, eventos de conversación. Estos viven en el Centro de administración en Aplicaciones e integraciones.

Los Webhooks de mensajería (Sunshine Conversations) manejan mensajes de chat en tiempo real a través de la plataforma de mensajería. Estos se configuran por separado y utilizan diferentes tipos de eventos.

¿El evento conversation.created que está buscando? Es parte del sistema de webhook estándar, no de la plataforma de mensajería. Esto confunde a muchos desarrolladores que esperan encontrarlo en la documentación de mensajería.

Entonces, ¿qué hace realmente este webhook? Cuando una nueva conversación comienza en su cuenta de Zendesk, ya sea desde el Web Widget, el SDK móvil, WhatsApp o cualquier otro canal, este webhook se activa y envía una carga útil a su punto final con todos los detalles de la conversación. Su aplicación puede entonces reaccionar en tiempo real: activar un agente de IA, registrar en su almacén de datos, enviar una notificación o enrutar la conversación en función del canal de origen.

Requisitos previos para configurar webhooks de mensajería

Antes de empezar a configurar los webhooks, asegúrese de que tiene:

• Acceso de administrador al Centro de administración de Zendesk: necesitará permisos para crear webhooks y gestionar integraciones.
• Una URL de punto final lista para recibir cargas útiles: debe ser una URL HTTPS de acceso público que pueda aceptar solicitudes POST.
• Conocimientos básicos de seguridad de webhook: querrá verificar las firmas para asegurarse de que las solicitudes realmente provienen de Zendesk.
• Un plan para gestionar los reintentos y los fallos: su punto final debe responder en un plazo de 12 segundos o Zendesk volverá a intentarlo.

Una limitación importante que debe conocer: las cuentas de prueba están limitadas a 10 webhooks y 60 invocaciones por minuto. Si está probando en una prueba, planifique en consecuencia.

Cómo crear un webhook de conversación en Zendesk

Hay dos maneras de configurar su webhook: a través de la interfaz de usuario del Centro de administración o a través de la API. La interfaz de usuario es más rápida para las configuraciones únicas, mientras que la API funciona mejor si está automatizando implementaciones o gestionando múltiples entornos.

Usando el Centro de administración

Paso 1: Acceder a la sección de webhooks

Navegue hasta el Centro de administración, luego haga clic en Aplicaciones e integraciones en la barra lateral. Seleccione Webhooks > Webhooks en el submenú.

Paso 2: Crear el webhook

Haga clic en Crear webhook y elija su método de conexión. Para los eventos de conversación, seleccione Eventos de Zendesk (no Disparador o Automatización).

La elección del método de conexión es permanente. Una vez que cree un webhook como "Eventos de Zendesk", no podrá convertirlo en un webhook basado en disparadores más adelante. Si necesita ambos tipos de eventos, cree webhooks separados.

Paso 3: Configurar los ajustes del webhook

Rellene la configuración básica:

• Nombre y descripción: utilice algo descriptivo como "Notificaciones de nueva conversación" para que su equipo sepa lo que hace.
• URL del punto final: su punto final HTTPS que recibirá las cargas útiles.
• Método de solicitud: POST (esto se fija para los webhooks suscritos a eventos).
• Formato de solicitud: JSON (también se fija para las suscripciones a eventos).

Paso 4: Seleccionar el evento de conversación creada

En la sección de suscripciones a eventos, seleccione zen:event-type:conversation.created en el menú desplegable. Puede suscribirse a varios eventos si es necesario (como conversation.updated o conversation.closed).

Paso 5: Configurar la autenticación

Elija su método de autenticación:

Para la producción, también debe habilitar la verificación de la firma. Zendesk firma cada solicitud con HMAC SHA256, y puede verificar la firma con el secreto de firma de su webhook para asegurarse de que las solicitudes son legítimas.

Usando la API

Para la configuración programática, utilice la API de Webhooks:

curl -X POST https://{subdomain}.zendesk.com/api/v2/webhooks \
  -u {email_address}/token:{api_token} \
  -H "Content-Type:application/json" \
  -d '{
    "webhook": {
      "name": "Webhook de conversación creada",
      "status": "active",
      "endpoint": "https://your-endpoint.com/webhook",
      "http_method": "POST",
      "request_format": "json",
      "subscriptions": [
        "zen:event-type:conversation.created"
      ],
      "authentication": {
        "type": "bearer_token",
        "data": {
          "token": "YOUR_TOKEN"
        },
        "add_position": "header"
      }
    }
  }'

La API devuelve un ID de webhook único que utilizará para la supervisión y las actualizaciones.

Comprender la carga útil del webhook de conversación creada

Cuando se crea una conversación, Zendesk envía una carga útil JSON a su punto final. Esto es lo que puede esperar:

{
  "account_id": 21825834,
  "detail": {
    "id": "141"
  },
  "event": {
    "conversation_id": "67ab5f53a96f98663935c3f2",
    "created_at": "2025-02-11T14:32:05Z",
    "source_channel": "web",
    "participant_count": 1
  },
  "id": "01JQMQH83YNAKWSWJ8B1QH2NSC",
  "subject": "zen:ticket:141",
  "time": "2025-02-11T14:32:05.254571515Z",
  "type": "zen:event-type:conversation.created",
  "zendesk_event_version": "2022-11-06"
}

Campos clave a los que debe prestar atención:

• detail.id: el ID del ticket asociado a esta conversación.
• event.conversation_id: el identificador único de la conversación.
• event.source_channel: dónde se originó la conversación (web, whatsapp, facebook, etc.).
• type: el tipo de evento que activó este webhook.

La estructura de la carga útil difiere de los webhooks de mensajería (que utilizan una matriz events anidada con tipos conversation:message). Los webhooks de conversación estándar tienen una estructura más plana centrada en el ciclo de vida de la conversación en lugar de en los mensajes individuales.

Autenticación y mejores prácticas de seguridad

Los webhooks son tan seguros como su proceso de verificación. Dado que su punto final es de acceso público, debe verificar que las solicitudes realmente provienen de Zendesk.

Verificación de la firma

Cada solicitud de webhook incluye dos encabezados:

• X-Zendesk-Webhook-Signature: la firma HMAC SHA256
• X-Zendesk-Webhook-Signature-Timestamp: marca de tiempo Unix de cuándo se envió la solicitud

Para verificar una solicitud:

1. Extraiga ambos encabezados de la solicitud entrante
2. Concatene la marca de tiempo y el cuerpo de la solicitud (marca de tiempo + "." + cuerpo)
3. Genere un hash HMAC SHA256 utilizando el secreto de firma de su webhook
4. Codifique el resultado en Base64
5. Compare con el encabezado de la firma

El algoritmo es: base64(HMACSHA256(TIMESTAMP + "." + BODY))

Puede encontrar su secreto de firma en el Centro de administración haciendo clic en "Revelar secreto" en la página de configuración de su webhook. Para las pruebas antes de crear el webhook, utilice este secreto de prueba estático: dGhpc19zZWNyZXRfaXNfZm9yX3Rlc3Rpbmdfb25seQ==

Requisito HTTPS

Utilice siempre puntos finales HTTPS para los webhooks de producción. Además de los beneficios de seguridad, algunas características como los encabezados personalizados y ciertos métodos de autenticación solo funcionan con HTTPS.

Idempotencia

Zendesk hace todo lo posible para entregar los webhooks exactamente una vez, pero no puede garantizarlo. Su punto final podría recibir el mismo evento de conversación creada varias veces, especialmente durante los reintentos o si se activa el cortacircuitos.

Diseñe su controlador para que sea idempotente: compruebe si ya ha procesado un ID de conversación antes de tomar medidas. Esto evita notificaciones duplicadas, entradas de CRM duplicadas o la activación de la misma automatización dos veces.

Gestión de eventos de webhook en su aplicación

Aquí hay un patrón básico para manejar los webhooks de conversación en Node.js:

const crypto = require('crypto');

app.post('/webhook', (req, res) => {
  // Verificar la firma
  const signature = req.headers['x-zendesk-webhook-signature'];
  const timestamp = req.headers['x-zendesk-webhook-signature-timestamp'];
  const payload = JSON.stringify(req.body);

  const expectedSignature = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(`${timestamp}.${payload}`)
    .digest('base64');

  if (signature !== expectedSignature) {
    return res.status(401).send('Firma no válida');
  }

  // Procesar el evento de forma asíncrona
  const event = req.body;

  if (event.type === 'zen:event-type:conversation.created') {
    // Cola para el procesamiento - no bloquee la respuesta
    processConversationCreated(event);
  }

  // Responder rápidamente para evitar reintentos
  res.status(200).send('OK');
});

Los principios clave:

• Verifique la firma antes de procesar
• Responda con 200 OK rápidamente (en 12 segundos)
• Procese el evento de forma asíncrona: no permita que su lógica de negocio bloquee la respuesta HTTP
• Maneje los eventos duplicados con elegancia

Patrones de integración comunes

Activación del agente de IA: cuando se crea una conversación, compruebe si un agente de IA debe manejarla primero antes de enrutarla a los agentes humanos. Compruebe el canal de origen, la hora del día o el segmento de clientes para tomar la decisión de enrutamiento.

Registro de CRM: registre el inicio de la conversación en su CRM para la elaboración de informes y el análisis. Incluya la fuente del canal para comprender desde dónde se ponen en contacto los clientes.

Notificaciones de Slack: envíe una notificación a un canal de Slack cuando comiencen las conversaciones de alta prioridad, o enrute diferentes canales a diferentes canales de Slack en función de la fuente.

Si está creando integraciones de IA y desea omitir por completo el desarrollo de webhook, eesel AI se conecta directamente a Zendesk y maneja el procesamiento de conversaciones sin requerir controladores de webhook personalizados. Escuchamos los eventos de conversación y generamos automáticamente respuestas contextuales basadas en su base de conocimientos.

Solución de problemas comunes de webhook

Incluso los webhooks configurados correctamente pueden fallar. Aquí le mostramos cómo diagnosticar y solucionar los problemas más comunes:

Errores de conexión

Activación del cortacircuitos

Si su punto final comienza a devolver errores, el cortacircuitos de Zendesk se activará para proteger su servidor de ser sobrecargado. Se activa cuando un porcentaje significativo de solicitudes falla dentro de un corto período de tiempo.

Cuando se activa, los webhooks se pausan brevemente. Después de la pausa, Zendesk lo intenta de nuevo. Si esa solicitud falla, el cortacircuitos activa otra pausa. Este ciclo continúa hasta que una solicitud tiene éxito.

Nota: El cortacircuitos normalmente no se activará en webhooks de bajo volumen, por lo que los pequeños entornos de prueba generalmente están a salvo de bloqueos accidentales.

Consejos de depuración

• Consulte los registros de actividad de webhook en el Centro de administración (se conservan durante 7 días)
• Filtre por estado para ver las invocaciones fallidas: agregue ?filter[status]=failed a la solicitud de la API
• Utilice herramientas como ngrok o Hookdeck para inspeccionar las cargas útiles reales durante el desarrollo
• Verifique que el formato de su carga útil coincida con lo que espera su punto final: la estructura difiere entre los webhooks estándar y los webhooks de mensajería

Referencia del comportamiento de reintento

Agilice las integraciones de webhook con eesel AI

La creación de controladores de webhook personalizados requiere un tiempo de desarrollo significativo. Debe manejar la verificación de la firma, la lógica de reintento, la idempotencia y el manejo de errores antes de llegar a su lógica de negocio real. Luego está el mantenimiento continuo: la supervisión, el registro y la actualización a medida que evolucionan las API de Zendesk.

Si su objetivo es la automatización del soporte impulsada por IA en lugar de la infraestructura de webhook, existe un camino más simple.

eesel AI se conecta directamente a su cuenta de Zendesk y maneja toda la complejidad del webhook por usted:

• Procesamiento de conversaciones en tiempo real: ingerimos eventos de tickets y mensajería a medida que suceden, sin necesidad de desarrollo de webhook por su parte
• Respuestas contextuales de IA: nuestro sistema utiliza su base de conocimientos, tickets anteriores y artículos del centro de ayuda para generar respuestas que coincidan con la voz de su marca
• Acciones más allá del texto: busque pedidos en Shopify, procese reembolsos, actualice los campos de los tickets y más, todo configurado a través de instrucciones en lenguaje natural en lugar de código
• Implementación gradual: comience con el modo copiloto donde los agentes revisan los borradores de IA, luego pase a las respuestas autónomas a medida que gane confianza

La configuración lleva minutos, no días. Conecte su cuenta de Zendesk, capacite con sus datos existentes y elija su modo. Puede ejecutar simulaciones en tickets anteriores para verificar la calidad antes de ponerlo en marcha.

Las implementaciones maduras que utilizan eesel AI logran hasta un 81% de resolución autónoma con períodos de recuperación típicos de menos de 2 meses. Si está considerando la creación de controladores de webhook personalizados para la integración de IA, pruebe eesel AI gratis durante 7 días primero y vea si cubre su caso de uso.

Comience a construir con los webhooks de conversación de Zendesk hoy mismo

El webhook de conversación creada es una herramienta poderosa para la automatización del soporte en tiempo real. Ya sea que esté activando agentes de IA, sincronizando datos con sistemas externos o enrutando notificaciones, comprender cómo configurar y manejar correctamente estos webhooks es esencial.

Recuerde la distinción clave: los webhooks estándar manejan los eventos del ciclo de vida de la conversación (creada, actualizada, cerrada), mientras que los webhooks de mensajería manejan el flujo de mensajes en tiempo real. El evento conversation.created vive en el sistema de webhook estándar, y es su punto de entrada para reaccionar a las nuevas conversaciones de los clientes en todos los canales.

Comience con la interfaz de usuario del Centro de administración para familiarizarse con la estructura de la carga útil, luego pase a la API cuando esté listo para automatizar. Habilite la verificación de la firma desde el primer día, diseñe para la idempotencia y responda rápidamente para evitar tormentas de reintento.

Para los equipos que construyen soporte impulsado por IA sin la sobrecarga de la infraestructura, eesel AI elimina la necesidad de controladores de webhook personalizados al tiempo que ofrece respuestas contextuales basadas en el conocimiento. De cualquier manera, el conocimiento de la conversación en tiempo real ahora está al alcance.