Los programadores web normalmente usan webhooks para invocar un comportamiento en otro sistema. Por ejemplo, los webhooks se pueden usar para:
Para crear grupos es necesario ser un administrador o un agente con un rol personalizado que tenga permiso para crear webhooks. Las cuentas de prueba admiten un máximo de 10 webhooks y tienen un límite de velocidad de 60 invocaciones por minuto.
Acerca de los webhooks
Hay dos maneras de conectar un webhook a la actividad en Zendesk Support:
- Suscribir el webhook a uno o más eventos de Zendesk. Utilice este método de conexión para enviar solicitudes en función de la organización, el usuario, la disponibilidad del agente, el centro de ayuda o la actividad de la comunidad. Si desea ver una lista de los tipos de eventos admitidos, consulte Tipos de eventos de webhook en la referencia de la API.
- Conectar el webhook a un disparador o una automatización. Utilice este método de conexión para enviar solicitudes en función de la actividad del ticket.
Un webhook que está suscrito a un evento de Zendesk no puede conectarse a un disparador o a una automatización. De manera similar, un webhook que está conectado a un disparador o a una automatización no puede suscribirse a eventos de Zendesk. No se puede cambiar el método de conexión de un webhook existente.
Suscripción a eventos de Zendesk
Un webhook que está suscrito a uno o más eventos de Zendesk siempre envía solicitudes usando el método HTTP POST. La solicitud incluye una carga JSON que contiene los datos del evento. No es posible cambiar el método HTTP ni la carga de la solicitud. Si desea más información sobre los esquemas de carga de eventos, consulte Webhook event types en la referencia de la API.
Conexión a disparadores y automatizaciones
-
JSON
-
XML
-
Contenido con codificación de formulario
El contenido de la solicitud se define a la hora de conectar el webhook a un disparador o una automatización. Para los webhooks que usan el método HTTP POST, PUT o PATCH con un formato de solicitud JSON o XML, el contenido es la carga de la solicitud. Los webhooks que usan otros métodos HTTP o formatos no incluyen una carga de solicitud. En su lugar, se pueden agregar parámetros de URL personalizados como una matriz de dos cadenas de clave-valor. Al definir la carga de la solicitud o los parámetros de URL, se puede usar cualquiera de los marcadores de posición de contenido disponibles para insertar datos de ticket en la solicitud.
Ni la carga de la solicitud ni los parámetros de URL del webhook pueden exceder los 256 KB.
Organización y reintentos de webhooks
Cuando un evento, un disparador o una automatización invoca un webhook, pone el trabajo del webhook que se debe ejecutar en la cola, pero no ejecuta el trabajo inmediatamente. Debido a que los trabajos del webhook se ejecutan de manera independiente, no hay ninguna garantía de que los webhooks vayan a ejecutarse en un orden determinado.
Las solicitudes de webhooks se vuelven a probar automáticamente hasta tres veces si los extremos devuelven ciertos códigos de respuesta HTTP. A diferencia de los destinos, los webhooks no se desactivan si hay solicitudes fallidas consecutivas. Si desea obtener más información y ver ejemplos de situaciones de reintento, consulte el artículo Monitoring webhooks que se encuentra en la documentación para desarrolladores.
Crear un webhook
Los webhooks se pueden crear en el Centro de administración.
Para crear un webhook
- En el Centro de administración, haga clic en
Aplicaciones e integraciones en la barra lateral y luego seleccione Acciones y webhooks > Webhooks. - Haga clic en Crear webhook.
- Para suscribir el webhook a uno o más eventos de Zendesk, seleccione Eventos de Zendesk y luego seleccione uno o más tipos de eventos en la lista desplegable.
- Para conectar el webhook a un disparador o una automatización, seleccione Disparador o automatización.
- Haga clic en Siguiente.
- Ingrese un Nombre y una Descripción para el webhook.
- Ingrese el URL de extremo que se usa para la integración con el servicio o sistema de terceros. Consulte Extremos de webhooks.
Al configurar un webhook para la integración con un tercero, puede ser necesario consultar la documentación del servicio de terceros.
- Seleccione el Método de solicitud y el Formulario de solicitud del webhook.
- Seleccione el método de Autenticación para el webhook y proporcione la información adicional que se necesite. Consulte Autenticar un webhook.
- (Opcional) Haga clic en Agregar encabezado para agregar un encabezado personalizado y luego ingrese el Nombre del encabezado y un Valor. Para agregar hasta cuatro encabezados más, haga clic en Agregar otro encabezado. Consulte Encabezados personalizados del webhook.Nota: No incluya información confidencial en los encabezados personalizados.
- (Opcional) Haga clic en Probar webhook para asegurarse de que esté funcionando como debe.
- Haga clic en Crear webhook para crear el webhook.
- Para los webhooks de disparador y automatización, tiene que conectar el webhook a un disparador o una automatización. Consulte Conectar el webhook a un disparador o una automatización de Support. Después de conectar el disparador o la automatización, vuelva a la página Crear webhook y haga clic en Finalizar configuración.
Una vez creado el webhook, podrá ver sus detalles, suscripciones y actividad en la página Webhooks del Centro de administración. Consulte Administración de webhooks.
Extremos de webhooks
Los webhooks envían solicitudes al URL de extremo que se especifica al crearlos. El URL de extremo usa el siguiente formato: https://www.yourdomain.com/path.
Aunque no es un requisito, se recomienda usar HTTP seguro (HTTPS). Si se proporciona un URL de extremo seguro, se puede activar la autenticación y pasar los datos de manera segura.
Encabezados personalizados del webhook
Los encabezados personalizados son una manera de incluir información adicional en la solicitud que el webhook envía, y pueden hacer más fácil la conexión con algunos servicios de terceros que tienen requisitos únicos para los encabezados de los webhooks. Tenga en cuenta los requisitos y las limitaciones siguientes para los encabezados personalizados:
- Para usar encabezados personalizados, se tiene que usar un URL de extremo seguro (HTTPS).
- No incluya las credenciales de autenticación ni otra información confidencial en los encabezados personalizados. En cambio, utilice los métodos de autenticación admitidos.
- Los nombres de los encabezados deben ser únicos y no pueden tener más de 128 caracteres. Se admiten todos los caracteres US-ASCII alfanuméricos, además de los siguientes símbolos:
!,#,$,%,&,',*,+,-,.,^,_,`,|y~. - Los valores de los encabezados pueden tener una longitud de hasta 1000 caracteres y son compatibles con todos los caracteres US-ASCII desde 0x20 hasta 0x7E.
- No se admiten los siguientes encabezados:
- accept-charset
- accept-encoding
- connection
- content-encoding
- content-length
- content-md5
- content-type
- date
- expect
- forwarded
- host
- keep-alive
- max-forwards
- origin
- proxy-authenticate
- referer
- server
- te
- trailer
- transfer-encoding
- upgrade
- user-agent
- via
- www-authenticate
- zendesk-api-version
- zendesk-ep
- Además, los encabezados no pueden comenzar con los siguientes prefijos:
- access-control
- x-amzn
- x-apigw
- x-datadog
- x-envoy
- x-forwarded
- x-zendesk
Autenticar un webhook
Si su webhook se está integrando con un extremo seguro, tiene tres opciones para autenticar el webhook y los datos que envía. Podría ser conveniente que consulte la documentación del servicio de terceros sobre los requisitos de autenticación de su extremo o que trabaje con un desarrollador de su equipo para determinar el método de autenticación correcto para su webhook.
- No se requiere: no hay ninguna autenticación configurada ni tampoco se requiere.
- Clave API: utilice una clave API para autenticar el webhook.
- Autenticación básica: utilice un nombre de usuario y una contraseña para autenticar el webhook.
- Token de portador: utilice un token de acceso OAuth para autenticar el webhook.
Si los desarrolladores desean más información sobre la autenticación de webhooks, consulte Webhook security and authentication.
Para mayor seguridad, también se puede verificar la firma del webhook. Si desea más información, consulte Verifying webhook authenticity.
Conectar un webhook a un disparador o una automatización
Para invocar un webhook de disparador y automatización, primero tiene que conectarlo a un disparador o una automatización. Los disparadores y las automatizaciones especifican las circunstancias en las cuales se debe invocar el webhook.
Para conectar un webhook a un disparador de Support
- En el Centro de administración, haga clic en
Objetos y reglas en la barra lateral y luego seleccione Reglas de negocio > Disparadores. -
Cree un nuevo disparador o edite uno existente. Para ello, pase el puntero del mouse por encima del icono de opciones (
) y haga clic en Editar. - Bajo Acciones, haga clic en Agregar acción. Seleccione Notificar a webhook y luego seleccione su webhook.
- Ingrese la carga de solicitud del webhook o los parámetros de URL en función del formato de solicitud del webhook. Ni la carga ni los parámetros pueden exceder los 256 KB.
- Haga clic en Guardar.
- En el Centro de administración, haga clic en Objetos y reglas en la barra lateral y luego seleccione Reglas de negocio > Automatizaciones.
-
Cree una nueva automatización o edite una existente. Para ello, pase el puntero del mouse por encima del icono de opciones () y haga clic en Editar.
- Bajo Realizar estas acciones, haga clic en el icono para agregar acción (
). Seleccione Notificaciones: Notificar a webhook y luego seleccione su webhook. - Ingrese la carga de solicitud del webhook o los parámetros de URL en función del formato de solicitud del webhook. Ni la carga ni los parámetros pueden exceder los 256 KB.
- Haga clic en Enviar.
Probar un webhook
En el Centro de administración, tiene la opción de probar el webhook con distintos orígenes de eventos y solicitudes. Además de acceder a los webhooks existentes con el fin de probarlos, también puede probar un webhook al crearlo o editarlo.
Para probar un webhook
- En el Centro de administración, haga clic en Aplicaciones e integraciones en la barra lateral y luego seleccione Acciones y webhooks > Webhooks.
- Ubique el webhook en la lista, haga clic en el icono del menú de opciones () en la fila del webhook y luego haga clic en Probar webhook.
- En el panel Probar webhook, seleccione un evento para probar. Esta es una solicitud de muestra que se puede usar para probar el URL de extremo.
- Ingrese los detalles de la solicitud de prueba: cuerpo, parámetros o encabezados de la solicitud.
- Haga clic en Enviar prueba. La respuesta se ve en el panel que se encuentra debajo de la solicitud de prueba.