Création de webhooks pour interagir avec les systèmes tiers

Accès rapide : Centre d’administration > Applications et intégrations > Webhooks > Webhooks

Un webhook envoie une demande HTTP à une URL spécifiée en réponse à une activité dans Zendesk Support. Par exemple, vous pouvez configurer un webhook pour envoyer des demandes quand un utilisateur est supprimé ou un nouveau ticket créé.

Les développeurs Web utilisent généralement un webhook pour invoquer un comportement dans un autre système. Par exemple, vous pouvez utiliser les webhooks pour :

Prévenir votre équipe dans Slack quand un ticket urgent est créé
Transmettre les détails de ticket à votre équipe de documentation dans Asana une fois un ticket résolu
Notifier votre système interne quand un événement de ticket important survient

Vous devez être un administrateur ou un agent dans un rôle personnalisé avec la permission de créer des webhooks. Les comptes d’essai sont limités à un maximum de 10 webhooks et une limite de débit de 60 invocations par minute.

Cet article aborde les sujets suivants :

À propos des webhooks
Création d’un webhook
Test d’un webhook

À propos des webhooks

Il y a deux façons de connecter un webhook à une activité dans Zendesk Support :

Abonnez le webhook à un ou plusieurs événements Zendesk. Utilisez cette méthode de connexion pour envoyer des demandes basées sur l’activité d’une organisation, d’un utilisateur, d’un centre d’aide ou d’une communauté. Pour une liste des types d’événement pris en charge, consultez Webhook - Types d’événement dans la documentation de référence de l’API.
Connectez le webhook à un déclencheur ou un automatisme. Utilisez cette méthode de connexion pour envoyer des demandes basées sur l’activité d’un ticket.

Un webhook qui est abonné à un événement Zendesk ne peut pas se connecter à un déclencheur ou un automatisme. De même, un webhook qui est connecté à un déclencheur ou un automatisme ne peut pas être abonné aux événements Zendesk. Vous ne pouvez pas changer la méthode de connexion d’un webhook existant.

Abonnement aux événements Zendesk

Un webhook qui est abonné à un ou plusieurs événements Zendesk envoie toujours les demandes en utilisant la méthode HTTP POST. La demande inclut une charge JSON qui contient les données de l’événement. Vous ne pouvez pas changer la méthode HTTP ni la charge pour la demande. Pour en savoir plus sur les schémas de charge des événements, consultez Webhooks - Types d’événements dans la documentation de référence de l’API.

Connexion aux déclencheurs ou automatismes

Si un webhook est connecté à un déclencheur ou un automatisme, vous pouvez personnaliser la méthode HTTP, le format et, le contenu des demandes du webhook. Vous sélectionnez la méthode HTTP et le format du corps de la demande quand vous créez le webhook. Les webhooks connectés à un déclencheur ou un automatisme prennent en charge les formats de corps de la demande suivants :

JSON
XML
Contenu codé du formulaire

Vous définissez le contenu de la demande quand vous connectez le webhook à un déclencheur ou un automatisme. Pour les webhooks qui utilisent la méthode HTTP POST, PUT ou PATCH avec un format de demande JSON ou XML, le contenu est la charge de la demande. Les webhooks qui utilisent d’autres méthodes HTTP ou d’autres formats n’incluent pas de charge de la demande. Par contre, vous pouvez ajouter des paramètres d’URL personnalisés sous la forme d’un tableau de deux chaînes clé-valeur.

Quand vous définissez la charge de la demande ou les paramètres de l’URL, vous pouvez utiliser toutes les balises de contenu disponibles pour insérer des données de ticket dans la demande.

Ordre des webhooks et nouvelles tentatives

Quand un événement, un déclencheur ou un automatisme invoque un webhook, ils mettent en file d’attente le travail du webhook à exécuter, mais ne l’exécutent pas immédiatement. Comme les tâches liées aux webhooks s’exécutent indépendamment, il n’y a aucune garantie que les webhooks s’exécutent dans un ordre particulier.

Les demandes de webhook sont automatiquement réessayées jusqu’à 3 fois si le point de terminaison renvoie certains codes de réponse HTTP. À la différence des cibles, l’échec de demandes consécutives ne désactive pas les webhooks. Pour en savoir plus et des exemples de scénarios de ré-essais, consultez Surveillance des webhooks dans la documentation destinée aux développeurs.

Création d’un webhook

Vous pouvez créer un webhook dans le Centre d’administration.

Pour créer un webhook

Dans le Centre d’administration, cliquez sur l’icône Applications et intégrations dans la barre latérale, puis sélectionnez Webhooks > Webhooks.
Cliquez sur Créer un webhook.
- Pour abonner le webhook à un ou plusieurs événements Zendesk, sélectionnez Événements Zendesk et sélectionnez un ou plusieurs types d’événement dans le menu déroulant.
- Pour connecter le webhook à un déclencheur ou un automatisme, sélectionnez Déclencheur ou Automatisme.
Cliquez sur Suivant.
Saisissez un nom et une description pour le webhook.
Saisissez l’URL du point de terminaison utilisée pour intégrer le service ou système tiers. Consultez Points de terminaison des webhooks.
Lors de la configuration d’un webhook à intégrer avec un tiers, vous devrez peut-être consulter la documentation du tiers.
Sélectionnez la méthode de la demande et le format de la demande pour le webhook.
Sélectionnez la méthode d’authentification pour le webhook et fournissez toutes informations supplémentaires requises. Consultez Authentification de votre webhook.
(facultatif) Cliquez sur Ajouter un en-tête pour ajouter un en-tête personnalisé, puis saisissez un nom d’en-tête et une valeur. Pour ajouter d’autres en-têtes (4 maximum), cliquez sur Ajouter un autre en-tête. Consultez En-têtes de webhook personnalisés.
Remarque – Ne placez pas d’informations sensibles dans vos en-têtes personnalisés.
(Facultatif) Cliquez sur Tester le webhook pour vérifier qu’il fonctionne correctement.
Cliquez sur Créer un webhook pour créer le webhook.
Pour les webhooks de déclencheur ou d’automatisme, vous devez connecter le webhook à un déclencheur ou un automatisme. Consultez Connexion d’un webhook à un déclencheur ou un automatisme Support. Une fois le déclencheur ou l’automatisme connecté, retournez à la page Créer un webhook et cliquez sur Terminer la configuration.

Une fois le webhook créé, vous pouvez consulter ses détails, ses abonnements et son activité à la page Webhooks du Centre d’administration. Consultez Gestion des webhooks.

Points de terminaison des webhooks

Les webhooks envoient des demandes à l’URL de point de terminaison spécifié lors de leur création. L’URL de point de terminaison utilise le format suivant : https://www.yourdomain.com/path.

Bien que cela ne soit pas obligatoire, l’utilisation de HTTP sécurisé (HTTPS) est recommandée. En fournissant une URL de point de terminaison sécurisé, vous pouvez activer l’authentification et transférer des données en toute sécurité.

En-têtes de webhook personnalisés

Les en-têtes personnalisés fournissent un moyen d’ajouter des informations supplémentaires à la demande qu’envoie votre webhook et peuvent simplifier la connexion avec certains services tiers qui ont des exigences d’en-têtes de webhook uniques. Notez les spécifications et limitations suivantes pour les en-têtes personnalisés :

Pour utiliser les en-têtes personnalisés, vous devez utiliser une URL du point de terminaison sécurisée (HTTPS).
N’incluez pas d’identifiants d’authentification ou autres informations sensibles dans les en-têtes personnalisés. Utilisez plutôt les méthodes d’authentification prises en charge.
Les noms d’en-tête doivent être uniques et ne pas dépasser 128 caractères. Tous les caractères ASCII américains alphanumériques sont pris en charge, ainsi que les symboles suivants : !, #, $, %, &, ', *, +, -, ., ^, _, `, | et ~.
Les valeurs des en-têtes peuvent faire jusqu’à 1 000 caractères de long et prennent en charge tous les caractères ASCII américains de 0x20 à 0x7E.

Authentification d’un webhook

Si votre webhook est intégré avec un point de terminaison sécurisé, vous avez 3 options pour authentifier le webhook et les données envoyées. Vous pouvez vouloir référencer une documentation tierce à propos des demandes d’authentification de votre point de terminaison ou travailler avec un développeur dans votre équipe pour déterminer la bonne méthode d’authentification pour votre webhook.

Aucune requise : aucune authentification n’est configurée ou requise.
Clé API : utilisez une clé API pour authentifier le webhook.
Authentification de base : utilisez un nom d’utilisateur et un mot de passe pour authentifier le webhook.
Token du porteur : utilisez un token d’accès OAuth pour authentifier le webhook.

Si vos développeurs ont besoin de plus amples informations au sujet de l’authentification des webhooks, consultez Sécurité et authentification de webhook.

Pour plus de sécurité, vous pouvez aussi vérifier la signature du webhook. Pour en savoir plus, consultez Vérification de l’authenticité des webhooks.

Connexion d’un webhook à un déclencheur ou un automatisme

Pour invoquer un webhook de déclencheur ou d’automatisme, vous devez d’abord le connecter à un déclencheur ou un automatisme. Les déclencheurs et les automatismes spécifient les circonstances dans lesquelles le webhook doit être invoqué.

Pour connecter un webhook à un déclencheur Support

Dans le Centre d’administration, cliquez sur l’icône Objets et règles dans la barre latérale, puis sélectionnez Règles de gestion > Déclencheurs.
Créez un nouveau déclencheur ou modifiez-en un qui existe déjà en plaçant votre curseur sur l’icône d’options () et en cliquant sur Modifier.
Pour les déclencheurs, sous Actions, cliquez sur Ajouter une action. Sélectionnez Notifier le webhook et choisissez votre webhook. Cliquez sur Enregistrer.

Pour connecter un webhook à un automatisme Support

Dans le Centre d’administration, cliquez sur l’icône Objets et règles dans la barre latérale, puis sélectionnez Règles de gestion > Automatismes.
Créez un nouvel automatisme ou modifiez-en un qui existe déjà en plaçant votre curseur sur l’icône d’options () et en cliquant sur Modifier.
Pour les automatismes, sous Exécuter ces actions, cliquez sur l’icône ajouter une action (). Sélectionnez Notifications : Notifier le webhook et choisissez votre webhook. Cliquez sur Envoyer.

Test d’un webhook

Dans le Centre d’administration, vous avez l’option de tester le webhook avec plusieurs sources d’événements et demandes. En plus de l’accès aux webhooks spécifiquement pour les tester, vous pouvez aussi tester un webhook pendant sa création ou sa modification.

Pour tester un webhook

Dans le Centre d’administration, cliquez sur l’icône Applications et intégrations dans la barre latérale, puis sélectionnez Webhooks > Webhooks.
Trouvez le webhook dans la liste, puis cliquez sur l’icône du menu des options () sur la ligne du webhook et cliquez sur Tester le webhook.
Dans le volet Tester le webhook, sélectionnez un événement à tester. C’est un exemple de demande que vous pouvez utiliser pour tester l’URL de votre point de terminaison.
Saisissez les détails de votre demande de test (corps, paramètres ou en-tête de la demande).
Cliquez sur Envoyer le test. La réponse est visible dans le volet en dessous de la demande de test.