{
"title": "Formato de la carga útil de webhook de Zendesk: Una guía completa para desarrolladores",
"slug": "zendesk-webhook-payload-format",
"locale": "es",
"date": "2026-03-02",
"updated": "2026-03-02",
"template": "default",
"excerpt": "Una guía completa para comprender los formatos de carga útil de webhook de Zendesk, desde la anatomía de la solicitud hasta los esquemas específicos de eventos y la verificación de seguridad.",
"categories": [
"Zendesk",
"Guides"
],
"tags": [
"Zendesk",
"Webhooks",
"API",
"Integration",
"Customer Support"
],
"readTime": 11,
"author": 16,
"reviewer": 14,
"seo": {
"title": "Formato de la carga útil de webhook de Zendesk: Una guía completa para desarrolladores",
"description": "Una guía completa para comprender los formatos de carga útil de webhook de Zendesk, desde la anatomía de la solicitud hasta los esquemas específicos de eventos y la verificación de seguridad.",
"image": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-34a7235d-94f7-4258-8c7a-bb8cb1fe95af"
},
"coverImage": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-34a7235d-94f7-4258-8c7a-bb8cb1fe95af",
"coverImageAlt": "Imagen del banner para el formato de la carga útil de webhook de Zendesk: Una guía completa para desarrolladores",
"coverImageWidth": 1920,
"coverImageHeight": 1080,
"faqs": {
"heading": "Preguntas frecuentes",
"type": "blog",
"answerType": "html",
"faqs": [
{
"question": "¿Cuál es el formato exacto de la carga útil de webhook de Zendesk para los eventos de creación de tickets?",
"answer": "Los eventos de creación de tickets utilizan un esquema JSON estándar con propiedades de nivel superior que incluyen type, account_id, id, time, subject, detail y event. El objeto detail contiene el registro completo del ticket con campos como id, subject, description, status, priority, requester_id y assignee_id."
},
{
"question": "¿Cómo verifico la autenticidad de un formato de carga útil de webhook de Zendesk?",
"answer": "Utilice la verificación de firma HMAC-SHA256. Extraiga los encabezados x-zendesk-webhook-signature y x-zendesk-webhook-signature-timestamp, luego calcule base64(HMACSHA256(TIMESTAMP + BODY)) utilizando el secreto de firma de su webhook. Compare esto con el encabezado de firma utilizando una comparación de tiempo constante."
},
{
"question": "¿Puedo personalizar el formato de la carga útil de webhook de Zendesk para los webhooks basados en disparadores?",
"answer": "Sí. Los webhooks de disparadores y automatización permiten una personalización completa utilizando marcadores de posición de Liquid como {{ticket.id}}, {{ticket.title}} y {{ticket.requester.email}}. Puede estructurar la carga útil como datos JSON, XML o con codificación de formulario."
},
{
"question": "¿Cuál es el tamaño máximo para un formato de carga útil de webhook de Zendesk personalizado?",
"answer": "Las cargas útiles personalizadas para webhooks de disparadores tienen un límite de tamaño máximo de 256 KB. Si su carga útil excede esto, Zendesk la trunca. Supervise las cargas útiles que incluyen campos de descripción grandes o datos de campos personalizados extensos."
},
{
"question": "¿El formato de la carga útil de webhook de Zendesk incluye encabezados de autenticación?",
"answer": "Cada solicitud de webhook incluye encabezados estándar: x-zendesk-account-id, x-zendesk-webhook-id, x-zendesk-webhook-invocation-id, x-zendesk-webhook-signature y x-zendesk-webhook-signature-timestamp. También puede configurar la clave API, la autenticación básica o el token de portador."
},
{
"question": "¿Cómo pruebo el formato de la carga útil de webhook de Zendesk durante el desarrollo?",
"answer": "Utilice webhook.site para capturar e inspeccionar las cargas útiles sin procesar, o utilice la función de prueba de webhook integrada de Zendesk en el Centro de administración. Para las pruebas previas a la creación, utilice el secreto de firma estático: dGhpc19zZWNyZXRfaXNfZm9yX3Rlc3Rpbmdfb25seQ=="
}
],
"supportLink": null
}
}
---
Los webhooks convierten su cuenta de Zendesk en un motor de notificaciones en tiempo real. En lugar de sondear las API en busca de actualizaciones, los webhooks envían datos a sus sistemas en el momento en que sucede algo: se crea un ticket, un agente actualiza una prioridad o un cliente envía comentarios. Pero para construir integraciones confiables, deberá comprender exactamente qué datos envía Zendesk y cómo están estructurados.
Esta guía desglosa el formato de la carga útil de webhook de Zendesk desde cero. Aprenderá sobre los dos tipos de webhooks que ofrece Zendesk, la estructura exacta de las cargas útiles de eventos, cómo verificar la autenticidad del webhook y consejos prácticos de implementación. Ya sea que esté construyendo una integración personalizada o conectando Zendesk a herramientas de terceros, comprender estos formatos de carga útil es esencial.
En eesel AI, procesamos datos de webhook de Zendesk y otras plataformas para impulsar la automatización inteligente. Obtener el formato de carga útil correcto es el primer paso para construir integraciones robustas y seguras.
## Los dos tipos de webhooks de Zendesk
Zendesk ofrece dos métodos de conexión de webhook fundamentalmente diferentes, y la elección que haga determina sus opciones de formato de carga útil. No puede cambiar esta decisión más adelante, por lo que vale la pena comprender ambos enfoques por adelantado.
### Webhooks suscritos a eventos
Estos webhooks se suscriben directamente a los [eventos del sistema de Zendesk](https://developer.zendesk.com/api-reference/webhooks/event-types/webhook-event-types/). Cuando se crea un usuario, cambia un [estado de ticket](https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/#status) o se actualiza una organización, Zendesk envía automáticamente un webhook a su punto final.
Esto es lo que necesita saber:
- **Método HTTP:** POST solamente
- **Formato de solicitud:** JSON solamente
- **Estructura de la carga útil:** Esquema fijo definido por Zendesk
- **Ideal para:** Notificaciones en tiempo real sobre la actividad del usuario, la organización, el centro de ayuda o la mensajería
La carga útil es predecible. Zendesk controla qué datos se envían, lo que significa menos flexibilidad pero también menos margen para errores de configuración.
### Webhooks de disparador y automatización
Estos se conectan a las reglas de negocio de Zendesk: [disparadores](https://developer.zendesk.com/api-reference/ticketing/business-rules/triggers/) y [automatizaciones](https://developer.zendesk.com/api-reference/ticketing/business-rules/automations/). Usted define exactamente cuándo se activa el webhook en función de las condiciones del ticket.
Características clave:
- **Métodos HTTP:** GET, POST, PUT, PATCH, DELETE
- **Formato de solicitud:** JSON, XML o con codificación de formulario
- **Estructura de la carga útil:** Totalmente personalizable utilizando marcadores de posición de Liquid
- **Ideal para:** Flujos de trabajo basados en tickets con lógica condicional
Este enfoque le da control completo sobre la carga útil. Usted decide qué datos incluir y cómo formatearlos.
### Elegir el enfoque correcto
| Factor | Suscrito a eventos | Disparador/automatización |
|--------|------------------|-------------------|
| Flexibilidad | Baja (esquema fijo) | Alta (cargas útiles personalizadas) |
| Complejidad de la configuración | Simple | Más complejo |
| Caso de uso | Eventos en todo el sistema | Flujos de trabajo específicos de tickets |
| Tamaño de la carga útil | Definido por el sistema | 256 KB máximo |
Si necesita reaccionar a los cambios de tickets con lógica personalizada, utilice webhooks de disparador. Para eventos del sistema más amplios, como la creación de usuarios o la actividad de mensajería, los webhooks suscritos a eventos son la mejor opción.
## Anatomía de una solicitud de webhook
Cada solicitud de webhook de Zendesk incluye encabezados HTTP estándar que proporcionan metadatos sobre la solicitud. Comprender estos encabezados es crucial para el enrutamiento, el registro y la verificación de seguridad.
### Encabezados estándar
| Encabezado | Descripción | Ejemplo |
|--------|-------------|---------|
| `x-zendesk-account-id` | Su identificador de cuenta de Zendesk | `123456` |
| `x-zendesk-webhook-id` | Identificador único para este webhook | `01F1KRFQ6BG29CNWFR60NK5FNY` |
| `x-zendesk-webhook-invocation-id` | ID de invocación específico | `8350205582` |
| `x-zendesk-webhook-signature` | Firma HMAC-SHA256 para la verificación | `EiqWE3SXTPQpPulBV6OSuuGziIishZNc1VwNZYqZrHU=` |
| `x-zendesk-webhook-signature-timestamp` | Marca de tiempo ISO 8601 | `2021-03-25T05:09:27Z` |
Los encabezados de firma son opcionales pero recomendados para integraciones de producción. Le permiten verificar que las solicitudes realmente provienen de Zendesk y ayudan a prevenir ataques de repetición.
### Diferencias en la estructura de la solicitud
Los webhooks suscritos a eventos siempre usan POST con cargas útiles JSON. El cuerpo contiene los datos completos del evento en un esquema estandarizado.
Los webhooks de disparador varían según su configuración. Una solicitud GET podría incluir parámetros en la URL, mientras que las solicitudes POST incluyen un cuerpo formateado como JSON, XML o datos con codificación de formulario según su configuración.
## Estructura y ejemplos de la carga útil del evento
Los webhooks suscritos a eventos utilizan un esquema JSON consistente en todos los tipos de eventos. Una vez que comprenda la estructura, analizar cualquier evento se vuelve sencillo.
### Esquema de evento estándar
Cada carga útil de evento incluye estas propiedades de nivel superior:
```json
{
"type": "zen:event-type:ticket.created",
"account_id": 12514403,
"id": "2b24ef10-19d4-4740-93cf-8f98ec4776c0",
"time": "2099-07-04T05:33:18Z",
"zendesk_event_version": "2022-06-20",
"subject": "zen:ticket:12345",
"detail": { /* resource details */ },
"event": { /* change information */ }
}
| Propiedad | Descripción |
|---|---|
type | El identificador del tipo de evento |
account_id | Su ID de cuenta de Zendesk |
id | ID de evento único |
time | Cuándo ocurrió el evento |
zendesk_event_version | Versión del esquema (actualmente "2022-06-20") |
subject | Dominio e identificador de recursos |
detail | Objeto de recurso completo |
event | Qué cambió (para eventos de actualización) |
Evento de ticket creado
Cuando se crea un nuevo ticket, Zendesk envía una carga útil como esta:
{
"account_id": 22129848,
"detail": {
"actor_id": "8447388090494",
"assignee_id": "8447388090494",
"brand_id": "8447346621310",
"created_at": "2025-01-08T10:12:07Z",
"description": "Necesito ayuda con mi pedido reciente",
"external_id": null,
"form_id": "8646151517822",
"group_id": "8447320466430",
"id": "5158",
"is_public": true,
"organization_id": "8447346622462",
"priority": "LOW",
"requester_id": "8447388090494",
"status": "OPEN",
"subject": "Solicitud de ayuda con el pedido",
"submitter_id": "8447388090494",
"tags": ["order-help"],
"type": "TASK",
"updated_at": "2025-01-08T10:12:07Z",
"via": { "channel": "web_service" }
},
"event": {
"meta": {
"sequence": {
"id": 39313930383633353634323835,
"position": 1
}
}
},
"id": "cbe4028c-7239-495d-b020-f22348516046",
"subject": "zen:ticket:5158",
"time": "2025-01-08T10:12:07.672717030Z",
"type": "zen:event-type:ticket.created",
"zendesk_event_version": "2022-11-06"
}
El objeto detail contiene el registro completo del ticket. El objeto event para los eventos de creación solo incluye metadatos sobre la secuencia del evento.
Evento de estado cambiado
Los eventos de actualización incluyen un objeto event más detallado que muestra lo que cambió:
{
"event": {
"current": "OPEN",
"meta": {
"sequence": {
"id": 39313930383633353634323835,
"position": 1
}
},
"previous": "NEW"
}
}
Las propiedades current y previous muestran los valores antes y después. Para los cambios de estado, los valores posibles incluyen: NEW, OPEN, PENDING, HOLD, SOLVED, CLOSED, DELETED, ARCHIVED y SCRUBBED.
Evento de prioridad cambiada
Los eventos de prioridad siguen el mismo patrón:
{
"event": {
"current": "URGENT",
"meta": { "sequence": { "id": 39313930383633353634323835, "position": 1 } },
"previous": "NORMAL"
}
}
Los valores de prioridad son: LOW, NORMAL, HIGH y URGENT.
Evento de comentario agregado
Cuando alguien agrega un comentario a un ticket:
{
"event": {
"comment": {
"author": {
"id": "8659716080510",
"is_staff": false,
"name": "John Smith"
},
"body": "¡Gracias por la rápida respuesta!",
"id": "8659716087550",
"is_public": true
},
"meta": { "sequence": { "id": 39313930383633353634323835, "position": 1 } }
}
}
El objeto de comentario incluye el texto completo, la información del autor y el estado de visibilidad.
Evento de etiquetas cambiadas
Para las actualizaciones de etiquetas, Zendesk muestra lo que se agregó y eliminó:
{
"event": {
"meta": { "sequence": { "id": 39313930383633353634323835, "position": 1 } },
"tags_added": ["urgent", "vip"],
"tags_removed": ["pending-review"]
}
}
Esta estructura facilita el seguimiento de los cambios de etiquetas sin comparar matrices completas.
Cargas útiles y marcadores de posición de webhook de disparador
Los webhooks de disparador y automatización le brindan control completo sobre el formato de la carga útil utilizando marcadores de posición de Liquid.
Marcadores de posición comunes
| Marcador de posición | Descripción |
|---|---|
{{ticket.id}} | ID del ticket |
{{ticket.title}} | Asunto del ticket |
{{ticket.description}} | Descripción del ticket |
{{ticket.status}} | Estado actual |
{{ticket.priority}} | Nivel de prioridad |
{{ticket.requester.email}} | Correo electrónico del solicitante |
{{ticket.requester.name}} | Nombre del solicitante |
{{ticket.assignee.email}} | Correo electrónico del asignado |
{{ticket.group.name}} | Nombre del grupo |
{{ticket.organization.name}} | Nombre de la organización |
{{ticket.tags}} | Etiquetas separadas por comas |
{{ticket.created_at}} | Marca de tiempo de creación |
{{ticket.updated_at}} | Marca de tiempo de la última actualización |
{{current_user.name}} | Usuario que activó la acción |
Ejemplo de carga útil JSON personalizada
Puede construir cargas útiles personalizadas como esta:
{
"event": "ticket_updated",
"ticket_id": "{{ticket.id}}",
"ticket_url": "{{ticket.url}}",
"subject": "{{ticket.title}}",
"description": "{{ticket.description}}",
"status": "{{ticket.status}}",
"priority": "{{ticket.priority}}",
"requester": {
"name": "{{ticket.requester.name}}",
"email": "{{ticket.requester.email}}"
},
"assignee": {
"name": "{{ticket.assignee.name}}",
"email": "{{ticket.assignee.email}}"
},
"tags": "{{ticket.tags}}",
"updated_by": "{{current_user.name}}"
}
Límites de tamaño de la carga útil
Las cargas útiles personalizadas tienen un tamaño máximo de 256 KB. Si su carga útil excede este límite, Zendesk la trunca. Querrá vigilar las cargas útiles que incluyen campos de descripción grandes o muchos campos personalizados.
Autenticación y seguridad
Asegurar sus puntos finales de webhook es fundamental. Zendesk proporciona múltiples opciones de autenticación para verificar las solicitudes entrantes.
Verificación de firma
El método más seguro utiliza firmas HMAC-SHA256. Zendesk genera una firma a partir de la marca de tiempo y el cuerpo de la solicitud, que puede verificar en su servidor.
Algoritmo: base64(HMACSHA256(TIMESTAMP + BODY))
Ejemplo de verificación de Node.js:
const crypto = require("crypto");
const SIGNING_SECRET = "your_webhook_signing_secret";
const SIGNING_SECRET_ALGORITHM = "sha256";
function isValidSignature(signature, body, timestamp) {
let hmac = crypto.createHmac(SIGNING_SECRET_ALGORITHM, SIGNING_SECRET);
let sig = hmac.update(timestamp + body).digest("base64");
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(sig)
);
}
Ejemplo de verificación de Python:
import hmac
import hashlib
import base64
def verify_signature(payload, signature, timestamp, secret):
message = timestamp + payload
computed = base64.b64encode(
hmac.new(
secret.encode('utf-8'),
message.encode('utf-8'),
hashlib.sha256
).digest()
).decode('utf-8')
return hmac.compare_digest(computed, signature)
Secretos de firma
Cada webhook tiene un secreto de firma único. Puede recuperarlo del Centro de administración de Zendesk haciendo clic en "Revelar secreto" en la página de detalles del webhook, o a través de la API en GET /api/v2/webhooks/{id}/signing_secret.
Para probar webhooks antes de la creación, utilice este secreto estático: dGhpc19zZWNyZXRfaXNfZm9yX3Rlc3Rpbmdfb25seQ==
Métodos de autenticación adicionales
Además de la verificación de firma, Zendesk admite:
- Autenticación de clave API: Agregue un encabezado personalizado con su clave API
- Autenticación básica: Nombre de usuario y contraseña o token de API
- Token de portador: Autenticación de token al estilo OAuth
Mejores prácticas de seguridad
- Utilice siempre puntos finales HTTPS
- Verifique las firmas en entornos de producción
- Valide las marcas de tiempo para evitar ataques de repetición (rechace las solicitudes de más de 5 minutos)
- Almacene los secretos en variables de entorno, nunca en el código
- Haga que sus controladores de webhook sean idempotentes (Zendesk puede reintentar o enviar duplicados)
Pruebas y resolución de problemas
Antes de implementar webhooks en producción, necesitará estrategias de prueba confiables.
Usando webhook.site
Webhook.site proporciona una URL temporal y gratuita que captura las solicitudes entrantes. Es perfecto para inspeccionar cargas útiles de webhook sin procesar durante el desarrollo. Obtiene una URL única que muestra los encabezados y el contenido del cuerpo en tiempo real.
Pruebas integradas de Zendesk
Al crear o editar un webhook en el Centro de administración, Zendesk proporciona una función de prueba. Puede enviar una carga útil de prueba a su punto final y ver la respuesta. Esto ayuda a verificar la conectividad y el formato de la carga útil antes de ponerlo en marcha.
Errores comunes y soluciones
| Error | Causa | Solución |
|---|---|---|
| 401 No autorizado | Fallo de autenticación | Compruebe las claves API, los tokens o la verificación de la firma |
| 403 Prohibido | El punto final rechazó la solicitud | Verifique que el punto final acepte POST/GET según lo configurado |
| 404 No encontrado | URL del punto final incorrecta | Vuelva a verificar la URL del webhook |
| Tiempo de espera | Punto final demasiado lento | Optimice el tiempo de respuesta o verifique la carga del servidor |
| Disparador del interruptor de circuito | Demasiados errores | Solucione los problemas del punto final y espere el restablecimiento automático |
Comportamiento de reintento
Zendesk reintenta los webhooks fallidos automáticamente:
- Errores HTTP 409: hasta 3 reintentos
- HTTP 429/503 con encabezado retry-after de menos de 60 segundos: reintentado
- Tiempos de espera (límite de 12 segundos): hasta 5 reintentos
El interruptor de circuito se activa cuando el 70% de las solicitudes fallan en 5 minutos o se producen más de 1000 errores. Pausa el webhook durante 5 segundos y luego intenta una solicitud. Si tiene éxito, se reanuda el funcionamiento normal.
Integración de webhooks con eesel AI
Los webhooks se vuelven más poderosos cuando se combinan con el procesamiento inteligente. En eesel AI, ayudamos a los equipos a automatizar los flujos de trabajo procesando datos de webhook de Zendesk y otras plataformas.
Así es como la integración de webhook mejora las operaciones de soporte:
- Triaje inteligente: Procese los webhooks de creación de tickets para categorizar y enrutar automáticamente los tickets en función del análisis de contenido
- Respuestas automatizadas: Active respuestas contextuales utilizando datos de webhook sobre el estado del ticket y los cambios de prioridad
- Enriquecimiento de datos: Combine las cargas útiles de webhook con fuentes de datos internas para proporcionar a los agentes un contexto completo del cliente
- Sincronización entre plataformas: Utilice webhooks para mantener Zendesk sincronizado con CRM, inventario u otros sistemas empresariales
Nuestra integración de Zendesk se conecta directamente a su cuenta, aprendiendo de sus tickets anteriores y del centro de ayuda para proporcionar automatización inteligente. Los webhooks extienden esta capacidad al habilitar activadores y acciones en tiempo real.
Conclusiones clave y mejores prácticas
La construcción de integraciones de webhook confiables requiere atención al detalle. Esto es lo que querrá recordar:
Elija el tipo de webhook correcto: Los webhooks suscritos a eventos funcionan mejor para las notificaciones en todo el sistema, mientras que los webhooks de disparador le brindan flexibilidad para los flujos de trabajo específicos de tickets.
Verifique las firmas en producción: La verificación de firma HMAC-SHA256 garantiza que las solicitudes provengan de Zendesk y no hayan sido manipuladas.
Maneje los reintentos con elegancia: Zendesk puede reintentar las solicitudes fallidas o enviar duplicados. Diseñe sus controladores para que sean idempotentes.
Supervise el estado del webhook: Utilice el registro de actividad y el estado del interruptor de circuito para detectar problemas de forma temprana.
Pruebe a fondo: Utilice herramientas como webhook.site para inspeccionar las cargas útiles antes de implementarlas en producción.
Comprender el formato de la carga útil de webhook de Zendesk es la base para construir integraciones robustas. Con el enfoque correcto de seguridad, pruebas y manejo de errores, puede crear conexiones confiables que mantengan sus sistemas sincronizados y a su equipo informado.
Compartir esta entrada
Article by
