zendesk-messaging-message-delivered-webhook
Written by
eesel Team
Last edited 24 febrero 2026
{
"title": "Cómo configurar webhooks de mensajes entregados de Zendesk Messaging",
"slug": "zendesk-messaging-message-delivered-webhook",
"locale": "es",
"date": "2026-02-20",
"updated": "2026-02-20",
"template": "default",
"excerpt": "Una guía paso a paso para desarrolladores sobre la implementación de webhooks de entrega de mensajes de Zendesk Messaging, que incluye tipos de eventos, estructuras de carga útil y estrategias de prueba.",
"categories": [
"Blog Writer AI"
],
"tags": [
"Zendesk",
"Webhooks",
"Messaging API",
"Delivery Events",
"Customer Support"
],
"readTime": 12,
"author": 16,
"reviewer": 14,
"seo": {
"title": "Cómo configurar webhooks de mensajes entregados de Zendesk Messaging",
"description": "Una guía paso a paso para desarrolladores sobre la implementación de webhooks de entrega de mensajes de Zendesk Messaging, que incluye tipos de eventos, estructuras de carga útil y estrategias de prueba.",
"image": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-11eff73c-1518-4049-a825-a219ddecedea"
},
"coverImage": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-11eff73c-1518-4049-a825-a219ddecedea",
"coverImageAlt": "Imagen de banner para Cómo configurar webhooks de mensajes entregados de Zendesk Messaging",
"coverImageWidth": 1920,
"coverImageHeight": 1080,
"faqs": {
"heading": "Preguntas frecuentes",
"type": "blog",
"answerType": "html",
"faqs": [
{
"question": "¿Cada mensaje de Zendesk Messaging activa un webhook de entrega?",
"answer": "Solo si se ha suscrito a los eventos de entrega y el mensaje se envía a través de un canal compatible. Los eventos de entrega de canal se activan para todos los mensajes. Los eventos de entrega de usuario solo se activan para los canales que admiten la confirmación a nivel de dispositivo."
},
{
"question": "¿Cuánto tiempo debo almacenar los datos de los eventos de entrega?",
"answer": "Depende de su caso de uso. Para la depuración, de 7 a 30 días suele ser suficiente. Para el análisis o el cumplimiento, es posible que necesite una retención más prolongada. Los propios registros de webhook de Zendesk se conservan durante 7 días, por lo que si necesita un historial más largo, debe almacenar los eventos usted mismo."
},
{
"question": "¿Puedo usar webhooks de mensajes entregados de Zendesk con varios canales simultáneamente?",
"answer": "Sí. Un webhook puede recibir eventos de entrega de todos los canales. El campo destination.type en la carga útil le indica de qué canal proviene cada evento."
},
{
"question": "¿Cuál es la diferencia entre los webhooks de activación de Zendesk y los webhooks de eventos para el seguimiento de la entrega?",
"answer": "Los webhooks de activación se activan en función de las condiciones de los tickets que defina. Los webhooks de eventos (como los eventos de entrega) se activan para cada ocurrencia del tipo de evento suscrito. Para el seguimiento de la entrega, necesita webhooks de eventos porque necesita capturar cada cambio de estado de entrega, no solo las condiciones específicas del ticket."
},
{
"question": "¿Cómo manejo los eventos de entrega retrasados para los mensajes de Zendesk Messaging?",
"answer": "Los eventos de entrega de usuario pueden llegar horas después de que se envió el mensaje (si un teléfono estaba desconectado, por ejemplo). Construya su sistema para manejar eventos fuera de orden. Use los ID de mensaje para correlacionar los eventos con la operación de envío original, y no asuma que los eventos llegan en orden cronológico."
},
{
"question": "¿Están disponibles los webhooks de mensajes entregados de Zendesk Messaging en todos los planes de Zendesk?",
"answer": "Los webhooks están disponibles en los planes de Zendesk Suite y en los planes de Support con el complemento Webhooks. La mensajería en sí requiere una suscripción a Zendesk Suite. Consulte los detalles de su plan o póngase en contacto con el soporte de Zendesk para confirmar el acceso a los webhooks."
}
],
"supportLink": null
}
}
---
Los webhooks convierten su Zendesk en un motor de notificaciones en tiempo real. En lugar de sondear en busca de actualizaciones, los webhooks envían datos a sus sistemas en el momento en que sucede algo. Para la mensajería específicamente, los webhooks de entrega le permiten rastrear si los mensajes realmente llegan a sus clientes. No solo entregados a WhatsApp o Twilio. Realmente entregados.
Esto importa porque "enviado" y "entregado" son dos cosas diferentes. Un mensaje podría salir de Zendesk, fallar a nivel de operador, y usted nunca lo sabría sin el seguimiento de la entrega. O podría permanecer sin entregar porque el teléfono de un cliente está desconectado. Los webhooks de entrega le brindan visibilidad del ciclo de vida completo del mensaje.
En esta guía, aprenderá cómo configurar webhooks de entrega de mensajes de Zendesk desde cero. Cubriremos los tres tipos de eventos de entrega, lo guiaremos paso a paso a través de la configuración y le proporcionaremos código funcional que puede adaptar para su propia implementación.
## Lo que necesitará
Antes de sumergirse, asegúrese de tener:
- Una cuenta de Zendesk con acceso de administrador (la configuración de webhook requiere permisos de administrador)
- Un punto final HTTPS para recibir cargas útiles de webhook (un servidor de desarrollo funciona bien para las pruebas)
- Familiaridad básica con los conceptos de JSON y HTTP
- Opcionalmente: una herramienta como Postman o curl para las pruebas
Si está construyendo esto para producción, también querrá pensar en la autenticación, el manejo de errores y la idempotencia. Tocaremos todos esos temas.
## Comprender los eventos de entrega de mensajes de Zendesk
La plataforma de mensajería de Zendesk envía tres tipos de eventos de entrega. Cada uno le dice algo diferente sobre dónde se encuentra su mensaje.
### Los tres tipos de eventos de entrega
| Tipo de evento | Cuándo se activa | Lo que le dice |
|------------|---------------|-------------------|
| `conversation:message:delivery:channel` | Mensaje entregado a la API del canal | El canal (WhatsApp, Twilio, etc.) aceptó el mensaje |
| `conversation:message:delivery:user` | El mensaje llegó al dispositivo del usuario | El cliente realmente recibió el mensaje |
| `conversation:message:delivery:failure` | La entrega falló | Algo salió mal; detalles del error incluidos |
Así es como funciona el flujo. Cuando envía un mensaje, primero llega a la API del canal. Si esa API acepta el mensaje, obtiene un evento `delivery:channel`. Para algunos canales (como WhatsApp o SMS a través de Twilio), es posible que más adelante obtenga un evento `delivery:user` que confirme que el mensaje llegó al dispositivo. Si algo falla en el camino, obtiene `delivery:failure` con información de error específica.
El indicador `isFinalEvent` le indica si vienen más eventos. Cuando `isFinalEvent: true`, este es el último webhook que recibirá para ese mensaje. Cuando `false`, el canal admite la confirmación de entrega a nivel de usuario, así que espere un seguimiento.
### El soporte del canal varía
No todos los canales pueden confirmar la entrega al usuario. Algunos solo confirman que recibieron el mensaje de Zendesk. Aquí está el desglose:
**Canales con confirmación de entrega completa (canal + usuario):**
- WhatsApp
- Twilio SMS
- MessageBird
- iOS SDK, Android SDK, Unity SDK, Web Widget
**Canales con entrega solo al canal:**
- Facebook Messenger
- Instagram
- LINE
- Telegram
- Viber
- WeChat
- X (Twitter)
- Apple Messages for Business
Para los canales sin confirmación del usuario, el evento `delivery:channel` tendrá `isFinalEvent: true`. Esa es su señal de que no vendrán más actualizaciones.
### Por qué esto importa para su implementación
Si está creando análisis sobre estos webhooks, querrá tener en cuenta esta variación. Una métrica de "entregado" significa cosas diferentes según el canal. Para WhatsApp, es la confirmación a nivel de dispositivo. Para Facebook Messenger, solo significa que la API de Facebook aceptó el mensaje.
## Paso 1: Crear un webhook en el Centro de administración de Zendesk
Repasemos la creación de su primer webhook de entrega.
Primero, navegue a **Centro de administración > Aplicaciones e integraciones > Webhooks**. Si no ve la opción Webhooks, verifique que su rol tenga los permisos adecuados. Obtenga más información en la [documentación de webhooks de Zendesk](https://developer.zendesk.com/documentation/webhooks/creating-and-monitoring-webhooks/).
Haga clic en **Crear webhook**. Verá un formulario con varios campos:
**Nombre:** Dele algo descriptivo como "Rastreador de entrega de mensajes" o "Eventos de entrega de producción".
**URL del punto final:** Aquí es donde Zendesk publicará (POST) las cargas útiles del webhook. Para el desarrollo, puede usar una herramienta como ngrok para exponer un servidor local. Para la producción, esta debe ser una URL HTTPS en su infraestructura.
**Método HTTP:** Seleccione POST. Los eventos de entrega siempre usan POST.
**Formato de solicitud:** Seleccione JSON.
No guarde todavía. Configuraremos las suscripciones a eventos y la autenticación en los siguientes pasos.
## Paso 2: Suscribirse a los eventos de entrega
En el formulario de creación de webhook, busque la sección **Suscripciones a eventos**. Aquí es donde especifica qué eventos deben activar su webhook.
Para el seguimiento de la entrega de mensajes, suscríbase a estos tres eventos:
1. `conversation:message:delivery:channel`
2. `conversation:message:delivery:user`
3. `conversation:message:delivery:failure`
Puede suscribirse a eventos adicionales si es necesario (como `conversation:message` para todos los mensajes), pero para el seguimiento de la entrega específicamente, estos tres son lo que desea.
**Opciones de filtrado de eventos:**
Si su integración es parte del conmutador, puede controlar si recibe eventos para conversaciones que no está administrando activamente. La configuración `deliverStandbyEvents` filtra esto. La mayoría de las integraciones establecen esto en `false` para recibir solo eventos para conversaciones activas.
Guarde el webhook. Zendesk le asignará una ID única (que comienza con `01`). Copie esta ID. La necesitará para las pruebas y para conectarse a los activadores si sigue esa ruta.
## Paso 3: Configurar la autenticación de webhook
Los webhooks sin autenticación son un riesgo de seguridad. Cualquiera que descubra la URL de su punto final podría enviar eventos falsos. Zendesk admite varios métodos de autenticación.
### Opciones de autenticación disponibles
| Método | Mejor para | Cómo funciona |
|--------|----------|--------------|
| Clave API (API key) | Integraciones simples | Verificación de clave basada en encabezado |
| Autenticación básica (Basic auth) | Compatibilidad con sistemas heredados | Nombre de usuario/contraseña en el encabezado de autorización |
| Token de portador (Bearer token) | Integraciones de API modernas | Verificación de token OAuth o JWT |
Para la mayoría de las implementaciones, la autenticación de clave API logra el equilibrio adecuado entre seguridad y simplicidad.
### Configuración en Zendesk
En el formulario de webhook, expanda la sección **Autenticación**. Seleccione su método preferido e ingrese las credenciales:
- Para la clave API: especifique el nombre del encabezado (por ejemplo, `X-API-Key`) y el valor de la clave
- Para el token de portador: ingrese el token que Zendesk debe incluir
- Para la autenticación básica: proporcione el nombre de usuario y la contraseña
### Verificación de firmas de webhook
Zendesk puede firmar webhooks usando HMAC-SHA256. Esto le permite verificar que las cargas útiles realmente provienen de Zendesk, no de un atacante. Consulte la [documentación de firma de webhook de Zendesk](https://developer.zendesk.com/documentation/webhooks/creating-and-monitoring-webhooks/#verifying-webhook-signatures) para obtener una guía de implementación detallada.
Para habilitar esto, deberá:
1. Generar un secreto de firma (Zendesk proporciona esto cuando habilita la firma)
2. Verificar el encabezado `X-Zendesk-Webhook-Signature` en su punto final
3. Calcular el HMAC-SHA256 de la carga útil usando su secreto
4. Compararlo con el encabezado de la firma
Aquí hay un ejemplo simple de Node.js:
```javascript
const crypto = require('crypto');
function verifyWebhookSignature(payload, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(payload, 'utf8')
.digest('base64');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}
Paso 4: Construir su punto final de webhook
Ahora viene la parte divertida: construir el punto final que recibe estos webhooks.
Requisitos básicos
Su punto final debe:
- Usar HTTPS (Zendesk rechaza las URL HTTP)
- Responder dentro de 10 segundos
- Devolver un código de estado 2xx para el procesamiento exitoso
- Manejar los eventos duplicados con elegancia (idempotencia)
Receptor de webhook de muestra (Node.js/Express)
Aquí hay un punto final mínimo pero listo para producción:
const express = require('express');
const app = express();
app.use(express.json());
app.post('/webhooks/zendesk-delivery', (req, res) => {
// Acknowledge receipt immediately
res.status(200).send('OK');
// Process events asynchronously
const events = req.body.events || [];
for (const event of events) {
handleDeliveryEvent(event);
}
});
function handleDeliveryEvent(event) {
const { type, payload } = event;
switch (type) {
case 'conversation:message:delivery:channel':
console.log(`Message ${payload.message.id} delivered to ${payload.destination.type}`);
break;
case 'conversation:message:delivery:user':
console.log(`Message ${payload.message.id} reached user`);
break;
case 'conversation:message:delivery:failure':
console.error(`Message ${payload.message.id} failed:`, payload.error);
break;
}
}
app.listen(3000, () => {
console.log('Webhook endpoint listening on port 3000');
});
Cosas clave que hace este ejemplo:
- Responde inmediatamente (200 OK) antes de procesar
- Procesa los eventos de forma asíncrona
- Maneja cada tipo de evento por separado
- Extrae las ID relevantes para el registro/depuración
Manejo de reintentos e idempotencia
Zendesk reintenta los webhooks fallidos (respuestas 4xx/5xx, tiempos de espera) hasta 3-5 veces, dependiendo del error. Esto significa que su punto final podría recibir el mismo evento varias veces.
Para manejar esto, implemente la idempotencia:
const processedEvents = new Set(); // Use Redis in production
function handleDeliveryEvent(event) {
if (processedEvents.has(event.id)) {
console.log(`Skipping duplicate event: ${event.id}`);
return;
}
// Process the event...
processedEvents.add(event.id);
}
En producción, use Redis o una base de datos para rastrear las ID de eventos procesados con TTL (tiempo de vida) para que la ventana de deduplicación coincida con el comportamiento de reintento de Zendesk.
Paso 5: Comprender la carga útil del webhook de entrega
Analicemos lo que realmente llega en estos webhooks.
Estructura de carga útil común
Todos los eventos de entrega comparten esta estructura de contenedor:
{
"app": {
"id": "5fb29b20fee5422428712475"
},
"webhook": {
"id": "5ff5e98b0d0c6d8925594923",
"version": "v2"
},
"events": [
{
"id": "5ff7595eafcaab0a685ff889",
"createdAt": "2021-01-07T18:56:30.666Z",
"type": "conversation:message:delivery:channel",
"payload": {
"conversation": { "id": "2d4fd3d00715d1e64611e248" },
"user": { "id": "71268330a47f5c4b541fce46" },
"destination": {
"type": "whatsapp",
"integrationId": "5ff75853b1c3000a6ad4f7f5"
},
"message": { "id": "5ff7595eb1c3000a6ad4f7fb" },
"isFinalEvent": false,
"externalMessages": [
{ "id": "wamid.HBgNNTUxQTk4MDUz5Tg4MRU..." }
]
}
}
]
}
Campos clave explicados
| Campo | Por qué es importante |
|---|---|
events[].id | ID de evento único. Úselo para la deduplicación. |
events[].payload.conversation.id | Vincula el evento a una conversación específica. |
events[].payload.message.id | El mensaje específico al que se refiere este evento. |
events[].payload.destination.type | Qué canal (whatsapp, twilio, etc.). |
events[].payload.isFinalEvent | Si vienen más eventos para este mensaje. |
events[].payload.externalMessages | ID de mensajes nativos del canal para la depuración. |
Detalles del evento de falla
Cuando la entrega falla, la carga útil incluye un objeto de error:
{
"error": {
"code": "bad_request",
"message": "Message failed to send because more than 24 hours have passed since the customer last replied.",
"underlyingError": {
"errors": [{
"code": 131047,
"title": "Re-engagement message",
"message": "Re-engagement message"
}]
}
}
}
El campo underlyingError contiene el error sin procesar de la API del canal. Esto es invaluable para la depuración. Los códigos de error de WhatsApp, por ejemplo, le dicen exactamente por qué se rechazó un mensaje.
Paso 6: Probar su implementación de webhook
Antes de ponerlo en marcha, debe verificar que todo funcione.
Usar el probador de webhook de Zendesk
En la página de configuración del webhook, haga clic en Probar webhook. Zendesk enviará una carga útil de prueba a su punto final y le mostrará la respuesta. Esto es útil para verificar la conectividad y la autenticación.
Sin embargo, la carga útil de prueba es genérica. No será un evento de entrega real. Para realizar pruebas realistas, debe activar flujos de mensajes reales.
Pruebas con mensajes reales
- Envíe un mensaje de prueba a través de Zendesk Messaging
- Verifique los registros de su punto final para los webhooks entrantes
- Verifique que la estructura de la carga útil coincida con las expectativas
- Confirme que su lógica de manejo de eventos procese cada tipo correctamente
Para los canales que admiten la entrega al usuario (como WhatsApp), puede verificar el flujo de dos eventos. El primer webhook debe tener isFinalEvent: false. El segundo (entrega al usuario) debe tener isFinalEvent: true.
Comprobación de los registros de actividad del webhook
Zendesk mantiene los registros de webhook durante 7 días. Navegue a Centro de administración > Aplicaciones e integraciones > Webhooks, seleccione su webhook y vea la pestaña Actividad. Esto muestra las entregas recientes, los códigos de respuesta y cualquier error.
Si no ve los webhooks esperados, verifique:
- ¿Está activo el webhook (no en pausa)?
- ¿Son correctas las suscripciones a eventos?
- ¿Está respondiendo su punto final con códigos de estado 2xx?
Solución de problemas comunes
Incluso con una configuración cuidadosa, las cosas salen mal. Estos son los problemas más comunes y cómo solucionarlos.
El webhook no se activa
Si no recibe webhooks cuando se envían mensajes:
- Verifique que el webhook esté activo (no en pausa o en estado de borrador)
- Verifique que los tipos de eventos correctos estén suscritos
- Para los webhooks conectados al activador, verifique que se cumplan las condiciones del activador
- Verifique los registros de actividad del webhook para detectar patrones de falla
Errores de autenticación (401/403)
Si Zendesk informa errores de autenticación:
- Verifique que su punto final esté verificando el encabezado correcto
- Confirme que la clave/token API no haya caducado
- Verifique la distinción entre mayúsculas y minúsculas en los nombres de los encabezados
- Si usa la verificación de firma, asegúrese de estar calculando el HMAC correctamente
Tiempos de espera e interruptor de circuito
Zendesk tiene un tiempo de espera de 10 segundos. Si su punto final tarda más:
- Responda inmediatamente (200 OK) y procese de forma asíncrona
- Use una cola de mensajes (SQS, RabbitMQ, etc.) para el procesamiento pesado
- Supervise los tiempos de procesamiento y optimice las operaciones lentas
El interruptor de circuito se dispara con una tasa de error del 70% o más de 1000 errores en 5 minutos. Si esto sucede, Zendesk pausa su webhook. Deberá solucionar el problema subyacente y reactivar el webhook manualmente.
Faltan eventos de entrega
Si ve algunos eventos pero no otros:
- Verifique la matriz de soporte del canal. No todos los canales envían confirmaciones de entrega al usuario.
- Para WhatsApp específicamente, los eventos de entrega al usuario pueden retrasarse o suprimirse si el mensaje se recibe fuera de un cierto período de tiempo.
- Verifique el comportamiento de
isFinalEvent. Si estruea nivel de canal, no seguirá ningún evento de entrega al usuario.
Mejores prácticas para la producción
Una vez que su webhook esté funcionando, considere estas recomendaciones de producción.
Manejo de errores y monitoreo
- Registre todos los recibos de webhook con ID de evento para la depuración
- Configure alertas para tasas de error elevadas
- Supervise los tiempos de respuesta del punto final
- Rastree las tasas de entrega por canal para detectar problemas temprano
Seguridad
- Siempre use HTTPS en producción
- Implemente la verificación de la firma del webhook
- Rote las claves API periódicamente
- No registre datos confidenciales de la carga útil
Retención de datos
Los eventos de entrega contienen metadatos del mensaje. Considere:
- Cuánto tiempo conservar los registros de eventos
- Si almacenar cargas útiles completas o solo campos clave
- Requisitos de cumplimiento (GDPR, etc.) para los datos de los mensajes
Cuándo sondear vs. usar webhooks
Los webhooks son ideales para actualizaciones en tiempo real. Pero si necesita datos históricos o eventos perdidos, es posible que deba complementar con el sondeo. La API de List Messages puede llenar los vacíos.
Agilice los flujos de trabajo de mensajería con eesel AI
La creación de puntos finales de webhook personalizados requiere tiempo de ingeniería. Debe manejar la autenticación, los reintentos, la idempotencia y los casos de error. Luego, debe construir la lógica de negocios real sobre esos eventos.
Construimos eesel AI para manejar esta complejidad por usted. En lugar de administrar los webhooks usted mismo, obtiene la automatización de mensajería llave en mano con el seguimiento de la entrega incorporado. Nuestro compañero de equipo de IA se integra con Zendesk (y Freshdesk, Gorgias y otros) para manejar las conversaciones de principio a fin.
Si está buscando un camino más rápido hacia la mensajería impulsada por IA, consulte nuestra guía completa para configurar webhooks de mensajería de Zendesk. Y si desea comparar opciones, consulte nuestro desglose de los mejores chatbots de IA para Zendesk.
Compartir esta entrada
Article by
