Comment configurer un webhook Zendesk pour les événements de création de ticket

Les webhooks sont l'un des outils les plus puissants de l'arsenal d'automatisation de Zendesk. Ils vous permettent d'envoyer des notifications en temps réel à des systèmes externes chaque fois que quelque chose se produit dans votre centre d'assistance. Lorsqu'un client soumet un nouveau ticket, un webhook peut alerter instantanément votre équipe dans Slack, mettre à jour votre CRM ou déclencher des flux de travail personnalisés dans vos propres applications.

La configuration d'un webhook Zendesk pour les événements de création de ticket n'est pas compliquée, mais il y a des décisions importantes à prendre en cours de route. Ce guide vous guide tout au long du processus, de la configuration initiale aux tests et au dépannage.

Ce dont vous aurez besoin

Avant de commencer, assurez-vous d'avoir :

• Un compte Zendesk Support sur le plan Team ou supérieur (les webhooks ne sont pas disponibles sur le plan Essential)
• Un accès administrateur ou un rôle personnalisé avec les autorisations de création de webhook
• Une URL de point de terminaison qui peut recevoir des requêtes HTTP POST (cela pourrait être un service comme Zapier, une API personnalisée ou un site de test de webhook)
• Un jeton API si vous prévoyez d'utiliser l'authentification (recommandé pour la production)

Les comptes d'essai ont certaines limitations : un maximum de 10 webhooks et 60 invocations par minute. C'est suffisant pour les tests, mais vous voudrez effectuer une mise à niveau avant de passer en direct avec une automatisation importante.

Étape 1 : Créer le webhook dans Zendesk

Tout d'abord, vous devez créer le webhook lui-même. Cela définit l'endroit où Zendesk enverra les données et comment il s'authentifiera.

Accédez à Centre d'administration → Applications et intégrations → Webhooks. Cliquez sur Actions en haut à droite, puis sélectionnez Créer un webhook.

Vous verrez un formulaire avec plusieurs champs à configurer :

Nom et description : Donnez à votre webhook un nom clair comme « Notification de nouveau ticket » afin de pouvoir l'identifier ultérieurement. La description est facultative, mais utile si vous avez plusieurs webhooks.

URL du point de terminaison : C'est là que Zendesk enverra les données du webhook. Il doit s'agir d'une URL HTTPS valide qui peut accepter les requêtes POST. Pour les tests, vous pouvez utiliser un service comme webhook.site pour voir les payloads sans créer votre propre point de terminaison.

Méthode HTTP : Pour les abonnements aux événements, cela doit être POST. Si vous vous connectez plutôt à des déclencheurs, vous pouvez choisir GET, POST, PUT, PATCH ou DELETE selon ce que votre point de terminaison attend.

Format de la requête : Pour les abonnements aux événements, cela doit être JSON. Les webhooks connectés aux déclencheurs prennent également en charge les formats XML et form-encoded.

Authentification : Ceci est fortement recommandé pour la production. Zendesk prend en charge trois méthodes :

• Clé API (API key) : Ajoute un en-tête personnalisé avec votre clé
• Authentification de base (Basic auth) : Nom d'utilisateur et mot de passe, encodés en base64
• Jeton de porteur (Bearer token) : Jeton de style OAuth 2.0 dans l'en-tête Authorization

Une fois que vous avez tout rempli, cliquez sur Créer en bas. Votre webhook est maintenant créé, mais pas encore connecté à des événements. C'est l'étape suivante.

Étape 2 : Choisir votre méthode de connexion

C'est là que vous devez prendre une décision importante. Zendesk offre deux façons de connecter les webhooks à l'activité des tickets, et vous ne pouvez pas changer cela plus tard sans supprimer et recréer le webhook.

Option A : Abonnement aux événements (zen:event-type:ticket.created)

Cette approche abonne votre webhook directement au flux d'événements de Zendesk. Lorsqu'un ticket est créé, votre webhook se déclenche.

Avantages :

• Se déclenche pour chaque ticket créé, garanti
• Configuration simple : aucun déclencheur nécessaire
• Livraison en temps quasi réel

Inconvénients :

• Structure de payload fixe (vous ne pouvez pas personnaliser les données envoyées)
• Pas de filtrage : vous obtenez chaque ticket, même le spam
• Doit utiliser POST et JSON

Option B : Webhook connecté à un déclencheur

Cette approche connecte votre webhook à un déclencheur Zendesk. Le déclencheur décide quand se déclencher en fonction des conditions que vous définissez.

Avantages :

• Contrôle total sur le moment où le webhook se déclenche (groupes spécifiques, priorités, balises)
• Payload personnalisable à l'aide d'espaces réservés Zendesk
• Peut filtrer le bruit (spam, tickets de test, etc.)

Inconvénients :

• Nécessite la création et la maintenance d'un déclencheur
• Configuration légèrement plus complexe

Lequel devriez-vous choisir ? Si vous avez besoin de chaque ticket et que cela ne vous dérange pas de filtrer de votre côté, utilisez les abonnements aux événements. Si vous ne voulez que des tickets spécifiques (comme les problèmes de haute priorité ou les tickets de certaines organisations), utilisez les webhooks connectés aux déclencheurs.

Étape 3 : Configurer le déclencheur (pour les webhooks connectés aux déclencheurs)

Si vous avez choisi l'option B, vous devez maintenant créer un déclencheur qui invoque votre webhook.

Accédez à Centre d'administration → Objets et règles → Déclencheurs. Cliquez sur Ajouter un déclencheur.

Définissez vos conditions :

Au minimum, ajoutez : Ticket | Est | Créé

Vous pouvez ajouter d'autres conditions pour filtrer les tickets qui déclenchent le webhook :

• La priorité est élevée ou urgente
• Le groupe est « Support technique »
• Les balises contiennent « escaladé »
• L'organisation est un client VIP spécifique

Ajoutez l'action de webhook :

Sous Actions, sélectionnez Notifier le webhook actif dans le menu déroulant. Choisissez le webhook que vous avez créé à l'étape 1.

Configurez le payload JSON :

C'est là que vous définissez les données envoyées à votre point de terminaison. Utilisez les espaces réservés Zendesk pour insérer les données du ticket :

{
  "ticket_id": "{{ticket.id}}",
  "subject": "{{ticket.title}}",
  "description": "{{ticket.description}}",
  "requester_email": "{{ticket.requester.email}}",
  "requester_name": "{{ticket.requester.name}}",
  "priority": "{{ticket.priority}}",
  "status": "{{ticket.status}}",
  "group": "{{ticket.group.name}}",
  "assignee": "{{ticket.assignee.name}}",
  "created_at": "{{ticket.created_at}}",
  "tags": "{{ticket.tags}}",
  "url": "{{ticket.link}}"
}

Zendesk remplacera chaque espace réservé par les données réelles du ticket lorsque le webhook se déclenchera. Vous pouvez également utiliser le balisage Liquid pour la logique conditionnelle.

Important : Ajoutez une condition d'annulation pour éviter les boucles infinies. Étant donné que le déclencheur se déclenche lorsqu'un ticket est créé et que le webhook peut mettre à jour le ticket, vous avez besoin d'une condition qui empêche le déclencheur de se déclencher à nouveau. Un modèle courant consiste à ajouter une balise dans votre réponse de webhook et à exclure les tickets avec cette balise.

Étape 4 : Tester votre webhook

Avant de vous fier à votre webhook en production, vous devez vérifier qu'il fonctionne.

Testez via les paramètres du webhook :

Retournez à Centre d'administration → Applications et intégrations → Webhooks. Trouvez votre webhook et cliquez sur le menu à trois points, puis sur Tester le webhook.

Zendesk enverra un payload de test à votre point de terminaison. Le test utilise un secret de signature statique (dGhpc19zZWNyZXRfaXNfZm9yX3Rlc3Rpbmdfb25seQ==) afin que vous puissiez vérifier la validation de la signature.

Testez avec un vrai ticket :

Créez un ticket de test dans Zendesk. Vérifiez votre point de terminaison pour vérifier :

• La requête est arrivée
• Le payload contient les données attendues
• Les en-têtes d'authentification sont présents (si configurés)
• La signature est validée (si vous utilisez HMAC)

Vérifiez les journaux d'activité du webhook :

Zendesk conserve les journaux des invocations de webhook pendant 7 jours. Vous pouvez y accéder via l'API Webhooks pour voir l'état de la livraison, les codes de réponse et toute erreur.

Comprendre le payload du webhook

Lorsque Zendesk envoie un webhook pour un événement de création de ticket, la structure du payload diffère en fonction de votre méthode de connexion.

Payload abonné à l'événement

Pour les abonnements directs aux événements, le payload suit un schéma fixe :

{
  "type": "zen:event-type:ticket.created",
  "account_id": 22129848,
  "id": "cbe4028c-7239-495d-b020-f22348516046",
  "time": "2025-01-08T10:12:07.672Z",
  "zendesk_event_version": "2022-11-06",
  "subject": "zen:ticket:5158",
  "detail": {
    "actor_id": "8447388090494",
    "assignee_id": "8447388090494",
    "brand_id": "8447346621310",
    "created_at": "2025-01-08T10:12:07Z",
    "description": "I need help with my order",
    "id": "5158",
    "is_public": true,
    "organization_id": "8447346622462",
    "priority": "LOW",
    "requester_id": "8447388090494",
    "status": "OPEN",
    "subject": "Order help needed",
    "tags": ["order", "help"],
    "via": { "channel": "web_service" }
  },
  "event": { "meta": { "sequence": { "id": 12345, "position": 1 } } }
}

Les champs clés incluent l'ID du ticket, l'objet, la description, l'ID du demandeur, la priorité, l'état et l'horodatage de la création.

Payload connecté au déclencheur

Pour les webhooks connectés aux déclencheurs, le payload est ce que vous avez défini dans l'action du déclencheur. Vous avez un contrôle total sur la structure et le contenu.

Authentification et sécurité

Les webhooks peuvent transporter des données de ticket sensibles, il est donc important de les sécuriser.

Méthodes d'authentification :

• Clé API (API key) : Ajoutez un en-tête comme X-API-Key: your-secret-key
• Authentification de base (Basic auth) : Nom d'utilisateur : mot de passe encodé en Base64 dans l'en-tête Authorization
• Jeton de porteur (Bearer token) : Style OAuth 2.0 Authorization: Bearer your-token

Vérification de la signature HMAC :

Zendesk prend en charge les signatures HMAC-SHA256 pour vérifier l'authenticité du webhook. Chaque webhook reçoit un secret de signature unique. Zendesk signe chaque requête en calculant un HMAC sur l'horodatage et le corps de la requête.

Votre point de terminaison doit :

1. Extraire la signature de l'en-tête x-zendesk-webhook-signature
2. Extraire l'horodatage de l'en-tête x-zendesk-webhook-signature-timestamp
3. Calculer la signature attendue à l'aide de votre secret de signature
4. Comparer en utilisant une comparaison à temps constant pour éviter les attaques de synchronisation

Meilleures pratiques :

• Utilisez toujours des points de terminaison HTTPS
• Vérifiez les signatures en production
• Stockez les secrets de signature en toute sécurité (pas dans les référentiels de code)
• Mettez en œuvre l'idempotence pour gérer les livraisons en double
• Renvoyez rapidement l'état 200 ; traitez de manière asynchrone si nécessaire

Dépannage des problèmes courants

Même avec une configuration soignée, les webhooks ne fonctionnent parfois pas comme prévu. Voici les problèmes les plus courants et comment les résoudre.

Webhook ne se déclenchant pas :

• Vérifiez les conditions de déclenchement : sont-elles réellement remplies ?
• Vérifiez que le déclencheur est actif (pas désactivé)
• Recherchez les conditions d'annulation qui pourraient empêcher l'exécution
• Confirmez que l'état du webhook est « actif »

Erreurs de point de terminaison (réponses 4xx, 5xx) :

• 410 Gone : Votre point de terminaison a renvoyé une erreur ; vérifiez les journaux de votre serveur
• 429 Too Many Requests : Vous êtes limité en termes de débit ; mettez en œuvre le backoff
• Erreurs 5xx : Problèmes côté serveur de votre côté

Problèmes de délai d'attente :

Zendesk a un délai d'attente strict de 10 secondes. Si votre point de terminaison ne répond pas dans les 10 secondes, Zendesk le marque comme ayant échoué et réessaie. Assurez-vous que votre point de terminaison répond rapidement, en traitant le travail lourd de manière asynchrone si nécessaire.

Coupe-circuit déclenché :

Si votre webhook échoue à un taux d'erreur de 70 % ou accumule plus de 1 000 erreurs en 5 minutes, Zendesk le désactive automatiquement. Vous devrez résoudre le problème sous-jacent et réactiver le webhook manuellement.

Journaux d'activité manquants :

Zendesk ne conserve les journaux d'activité des webhooks que pendant 7 jours. Si vous avez besoin d'une conservation plus longue, vous devrez enregistrer les événements de webhook sur votre propre infrastructure.

Alternative : Automatiser sans webhooks

Les webhooks sont puissants, mais ce ne sont pas toujours le bon outil. Ils nécessitent une configuration technique, une maintenance continue et une gestion des erreurs. Si vous voulez l'automatisation sans la complexité, il existe des alternatives.

Nous avons créé eesel AI pour gérer l'automatisation du support sans nécessiter de webhooks ni de développement personnalisé. Au lieu de configurer des points de terminaison et d'analyser des payloads JSON, vous connectez simplement eesel AI à votre compte Zendesk. Il apprend de vos tickets passés et de vos articles du centre d'aide, puis gère automatiquement les tâches de routine.

Voici la différence :

Avec eesel AI, vous pouvez :

• Étiqueter et acheminer automatiquement les tickets en fonction du contenu
• Rédiger des réponses pour vos agents
• Gérer les questions courantes de bout en bout
• Escalader les problèmes complexes aux humains

Le meilleur dans tout ça ? Vous pouvez le tester sur les tickets passés avant de passer en direct. Aucun risque de casser les flux de travail de production pendant que vous affinez la configuration.

Commencez à automatiser vos flux de travail Zendesk dès aujourd'hui

La configuration d'un webhook Zendesk pour les événements de création de ticket vous donne une visibilité en temps réel sur les nouvelles demandes de support. Que vous notifiiez les canaux Slack, que vous synchronisiez avec un CRM ou que vous déclenchiez des flux de travail personnalisés, les webhooks fournissent le lien entre Zendesk et le reste de votre pile.

Le processus est simple : créez le webhook, choisissez votre méthode de connexion, configurez un déclencheur (si nécessaire) et testez minutieusement. Faites attention à l'authentification et à la gestion des erreurs pour assurer un fonctionnement fiable.

Si les webhooks vous semblent excessifs pour vos besoins, déterminez si une approche basée sur l'IA pourrait mieux fonctionner. Les outils comme eesel AI peuvent automatiser la gestion des tickets sans aucune configuration de webhook ni gestion des points de terminaison. Vous pouvez essayer eesel AI gratuitement et voir comment il gère vos types de tickets spécifiques avant de vous engager dans une solution basée sur un webhook.

Quoi qu'il en soit, l'objectif est le même : passer moins de temps sur la gestion manuelle des tickets et plus de temps à aider réellement les clients.