Comment configurer les webhooks Zendesk pour les mises à jour de tickets : Guide complet

Les webhooks Zendesk vous permettent de créer des intégrations en temps réel qui répondent à l'activité des tickets. Lorsqu'un ticket est mis à jour, qu'il s'agisse d'un changement d'agent, d'un changement de statut ou d'un nouveau commentaire, vous pouvez automatiquement notifier les systèmes externes sans écrire de scripts d'interrogation complexes.

Ce guide vous explique comment configurer un webhook qui se déclenche lorsque les tickets sont mis à jour. Vous apprendrez les étapes exactes pour configurer les webhooks dans le Centre d'administration de Zendesk, les connecter à des déclencheurs et gérer les problèmes courants qui piègent les nouveaux implémenteurs.

Que sont les webhooks Zendesk et pourquoi les utiliser ?

Les webhooks sont des rappels HTTP qui envoient des requêtes à une URL spécifiée lorsque quelque chose se produit dans Zendesk. Considérez-les comme des notifications automatisées qui envoient des données à vos systèmes au lieu de vous obliger à les extraire.

Zendesk offre deux façons de connecter les webhooks :

• Les webhooks abonnés aux événements se déclenchent pour chaque occurrence d'un événement système. Abonnez-vous à « ticket mis à jour » et votre endpoint reçoit un payload chaque fois qu'un ticket est modifié. Ceux-ci utilisent des payloads JSON fixes et des requêtes POST.

• Les webhooks connectés à un déclencheur ou à une automatisation se déclenchent en fonction des conditions que vous définissez. Vous choisissez exactement quand ils se déclenchent (agent modifié, priorité définie sur urgente, etc.) et personnalisez le payload à l'aide d'espaces réservés Zendesk.

Les cas d'utilisation courants des webhooks de mise à jour de tickets incluent la synchronisation des données de ticket vers un CRM, l'alerte des canaux Slack concernant les changements de haute priorité, le déclenchement de workflows personnalisés dans vos outils internes et la création de pistes d'audit pour la conformité.

Le principal avantage est la réactivité en temps réel. Au lieu d'interroger l'API de Zendesk toutes les quelques minutes pour vérifier les changements, vous serez averti instantanément lorsque quelque chose se produit.

Pour les équipes qui trouvent la configuration des webhooks trop technique ou trop longue, eesel AI offre une approche alternative. Plutôt que de construire et de maintenir l'infrastructure de webhook, eesel se connecte directement à Zendesk et gère l'automatisation grâce à l'IA qui apprendra de vos tickets existants.

Ce dont vous aurez besoin avant de commencer

Avant de créer votre premier webhook, assurez-vous d'avoir :

• Un accès administrateur à Zendesk : seuls les administrateurs peuvent créer et gérer des webhooks via le Centre d'administration
• Un jeton API : générez-le dans le Centre d'administration sous Applications et intégrations > Jetons API
• Un endpoint de réception : une URL qui peut accepter les requêtes HTTP POST et traiter les payloads JSON
• Une compréhension de base de JSON : vous construirez des payloads avec des données de ticket

Facultatif mais recommandé : configurez un inspecteur de requêtes comme Hookdeck Console ou webhook.site pour les tests. Ces outils vous donnent une URL temporaire pour capturer les requêtes de webhook et inspecter la structure du payload avant de connecter votre endpoint de production.

Étape par étape : Création d'un webhook pour les mises à jour de tickets

Étape 1 : Accédez aux webhooks dans le Centre d'administration

Connectez-vous à Zendesk et accédez au Centre d'administration. Allez dans Applications et intégrations > Webhooks. Consultez la documentation officielle des webhooks Zendesk pour plus de détails.

Si c'est votre premier webhook, la liste sera vide. Cliquez sur le menu déroulant Actions en haut à droite, puis sélectionnez Créer un webhook.

Étape 2 : Créer un nouveau webhook

Vous verrez deux options de connexion :

• Déclencheur ou automatisation : pour les workflows basés sur les tickets avec des conditions personnalisées
• Événements Zendesk : pour les abonnements aux événements à l'échelle du système

Choisissez Déclencheur ou automatisation, car vous voudrez déclencher le webhook lorsque les tickets sont mis à jour avec des conditions spécifiques.

Donnez à votre webhook un nom descriptif comme « Notification de mise à jour de ticket » afin de pouvoir l'identifier ultérieurement lors de la connexion aux déclencheurs.

Étape 3 : Configurer les paramètres du webhook

Remplissez les détails du endpoint :

• URL du endpoint : l'URL HTTPS où Zendesk enverra les requêtes POST
• Méthode de requête : choisissez en fonction des exigences de votre endpoint (POST pour la plupart des cas d'utilisation, PUT pour la mise à jour des ressources)
• Format de requête : JSON est recommandé pour les données de ticket

L'URL du endpoint doit être accessible au public. Zendesk ne peut pas envoyer de webhooks à localhost ou à des adresses réservées à un usage interne. Si vous testez, utilisez un service comme ngrok pour tunnéliser votre serveur de développement local.

Étape 4 : Configurer l'authentification

Choisissez comment Zendesk s'authentifie auprès de votre endpoint :

• Aucun : aucune authentification (non recommandé pour la production)
• Authentification de base : nom d'utilisateur et mot de passe dans l'en-tête Authorization
• Jeton Bearer : authentification par jeton de style OAuth 2.0
• Clé API : en-tête personnalisé avec un nom de clé et une valeur

Pour l'authentification de base, utilisez votre adresse e-mail Zendesk avec /token ajouté comme nom d'utilisateur (par exemple, vous@company.com/token) et votre jeton API comme mot de passe.

Étape 5 : Tester le webhook

Avant d'enregistrer, cliquez sur le bouton Tester. Zendesk enverra un exemple de payload à votre endpoint.

Entrez un ID de ticket existant pour le test. Le payload de test ne mettra rien à jour, il vérifie simplement la connectivité.

Vérifiez les journaux de votre endpoint ou l'inspecteur de requêtes pour confirmer que le test est arrivé. Si vous voyez une réponse 200, la configuration de votre webhook fonctionne.

Étape 6 : Créer un déclencheur pour déclencher le webhook

Vous avez maintenant besoin d'un déclencheur qui invoque votre webhook lorsque les tickets sont mis à jour. Allez dans Objets et règles > Déclencheurs et cliquez sur Ajouter un déclencheur.

Définissez les conditions qui déterminent quand le webhook se déclenche :

• Ticket > Le ticket est : Mis à jour
• Ajoutez toutes les conditions supplémentaires (facultatif) : Ticket > Agent > Modifié, Ticket > Statut > Modifié en, etc.

Pour l'action, sélectionnez Notifier le webhook actif et choisissez le webhook que vous venez de créer dans le menu déroulant.

Étape 7 : Configurer les conditions de déclenchement et le payload

Dans l'action de déclenchement, vous définirez le payload JSON qui est envoyé à votre endpoint. Utilisez les espaces réservés Zendesk pour inclure les données du ticket :

{
  "ticket_id": "{{ticket.id}}",
  "subject": "{{ticket.title}}",
  "status": "{{ticket.status}}",
  "assignee": "{{ticket.assignee.name}}",
  "requester": "{{ticket.requester.email}}",
  "updated_at": "{{ticket.updated_at_with_timestamp}}"
}

L'espace réservé ticket.updated_at_with_timestamp est particulièrement utile pour les workflows de webhook, car il contient l'heure exacte de la mise à jour, que vous pouvez utiliser pour éviter les conditions de concurrence.

Enregistrez le déclencheur. Votre webhook est maintenant en ligne et se déclenchera chaque fois que les tickets correspondant à vos conditions seront mis à jour.

Exemples courants de payload de webhook

Voici des configurations de payload pratiques pour les scénarios courants :

Notification de mise à jour de ticket de base :

{
  "event": "ticket_updated",
  "ticket_id": "{{ticket.id}}",
  "subject": "{{ticket.title}}",
  "status": "{{ticket.status}}",
  "priority": "{{ticket.priority}}"
}

Alerte de changement d'agent :

{
  "event": "assignee_changed",
  "ticket_id": "{{ticket.id}}",
  "new_assignee": "{{ticket.assignee.name}}",
  "new_assignee_email": "{{ticket.assignee.email}}",
  "previous_assignee": "{{ticket.assignee.previous.name}}"
}

Changement de statut avec commentaire :

{
  "event": "status_changed",
  "ticket_id": "{{ticket.id}}",
  "new_status": "{{ticket.status}}",
  "latest_comment": "{{ticket.latest_comment}}",
  "ticket_url": "{{ticket.link}}"
}

Mise à jour du champ personnalisé :

{
  "ticket_id": "{{ticket.id}}",
  "custom_fields": [
    {"id": 12345, "value": "{{ticket.ticket_field_12345}}"},
    {"id": 67890, "value": "{{ticket.ticket_field_67890}}"}
  ]
}

Dépannage des problèmes courants

Le webhook ne se déclenche pas

Vérifiez attentivement les conditions de votre déclencheur. Une erreur courante consiste à utiliser « Le ticket est créé » au lieu de « Le ticket est mis à jour », ou à définir des conditions qui ne correspondent jamais (comme exiger qu'un champ soit à la fois vide et rempli).

Ajoutez temporairement une action « Ajouter des balises » à votre déclencheur. Si la balise est ajoutée mais que le webhook ne se déclenche pas, le problème vient de la configuration du webhook. Si la balise n'est pas ajoutée, les conditions de votre déclencheur sont incorrectes.

Erreurs d'authentification

Pour l'authentification de base, vérifiez que vous utilisez email@domain.com/token comme nom d'utilisateur (avec /token ajouté) et la chaîne de jeton API réelle comme mot de passe, et non votre mot de passe Zendesk.

Délai d'attente de 10 secondes

Zendesk applique un délai d'attente strict de 10 secondes. Votre endpoint doit répondre avec un code de statut 2xx dans ce délai. Si vous devez effectuer des opérations lentes, répondez immédiatement avec 200 et traitez de manière asynchrone dans une tâche en arrière-plan.

Activation du coupe-circuit

Si 70 % de vos requêtes de webhook échouent en 5 minutes, ou si vous atteignez plus de 1 000 erreurs, Zendesk active un coupe-circuit qui interrompt les livraisons pendant 5 secondes. Les événements pendant ces pauses sont enregistrés comme « coupe-circuit », mais ne sont jamais livrés. Surveillez l'état de santé de votre endpoint et corrigez rapidement les problèmes pour éviter cela.

Livraisons en double

Zendesk peut envoyer le même webhook plusieurs fois. Utilisez l'en-tête x-zendesk-webhook-invocation-id pour dédupliquer. Stockez les ID traités dans Redis ou votre base de données avec une durée de vie (TTL) de 24 heures.

Vérification des journaux d'invocation

Allez dans Applications et intégrations > Webhooks, cliquez sur votre webhook, puis sur l'onglet Invocations. Vous pouvez voir les 7 derniers jours de tentatives de livraison, y compris les détails de la requête et de la réponse. C'est votre principal outil de débogage.

Bonnes pratiques pour les webhooks de production

Utilisez toujours des endpoints HTTPS. Les webhooks HTTP non chiffrés sont vulnérables à l'interception et ne doivent pas être utilisés en production.

Vérifiez les signatures de webhook. Zendesk signe chaque requête avec HMAC-SHA256. Vérifiez la signature à l'aide du secret de signature de votre webhook pour vous assurer que les requêtes proviennent réellement de Zendesk, et non d'un attaquant.

Implémentez l'idempotence. Stockez les ID d'invocation traités et ignorez les doublons. Cela empêchera le double traitement lorsque Zendesk réessaie les livraisons échouées.

Répondez immédiatement. Renvoyez une réponse 200 aussi rapidement que possible, puis traitez les données du webhook de manière asynchrone. Cela vous maintient sous le délai d'attente de 10 secondes et empêche les tempêtes de nouvelles tentatives.

Surveillez l'état de santé du webhook. Interrogez régulièrement l'API d'invocations de webhook pour détecter les échecs avant qu'ils ne deviennent critiques. Zendesk n'envoie pas de notifications d'échec, vous devez donc vérifier de manière proactive.

Gérez les nouvelles tentatives avec élégance. Zendesk réessaiera les réponses 409 jusqu'à 3 fois, et les réponses 429/503 avec des en-têtes retry-after. Concevez votre endpoint pour les gérer avec élégance sans créer de données en double.

Une alternative plus simple : eesel AI pour l'automatisation des tickets

La configuration des webhooks nécessite une expertise technique, une maintenance continue et une surveillance attentive. Si votre équipe recherche l'automatisation des tickets sans les frais généraux d'ingénierie, eesel AI offre une approche différente.

Au lieu de construire une infrastructure de webhook, vous connectez eesel AI à votre compte Zendesk et il apprend de vos tickets existants, des articles du centre d'aide et des macros. L'IA gère ensuite l'automatisation via des actions Zendesk natives, vous n'avez donc pas besoin de webhooks.

Principales différences par rapport à l'automatisation basée sur les webhooks :

• Configuration sans code : connectez Zendesk en quelques minutes sans écrire de code ni configurer de endpoints
• Routage basé sur l'IA : balise, priorise et achemine automatiquement les tickets en fonction du contenu, et pas seulement des changements de champ
• Apprentissage continu : s'améliore au fil du temps à mesure qu'il voit plus de vos tickets et des corrections des agents
• Fiabilité intégrée : pas de coupe-circuits, de problèmes de délai d'attente ou de logique de nouvelle tentative à gérer

eesel AI peut rédiger des réponses, escalader des problèmes complexes, mettre à jour les champs de ticket et même traiter les remboursements via l'intégration Shopify, le tout sans configuration de webhook.

Commencez à automatiser votre workflow Zendesk dès aujourd'hui

Les webhooks Zendesk vous offrent de puissantes capacités d'intégration en temps réel. En suivant les étapes de ce guide, vous pouvez configurer des notifications de mise à jour de ticket qui envoient des données à votre CRM, déclenchent des workflows internes ou alertent instantanément les canaux de l'équipe.

Les webhooks sont utiles lorsque vous avez besoin d'un contrôle total sur l'intégration, que vous disposez de ressources d'ingénierie pour construire et maintenir les endpoints et que vous avez besoin de formats de payload personnalisés. Ils sont le bon choix pour les workflows complexes et multi-systèmes.

Pour les équipes qui souhaitent bénéficier des avantages de l'automatisation sans la complexité technique, eesel AI gère le routage, le balisage et les réponses des tickets grâce à l'IA qui apprend votre activité. C'est un chemin plus rapide vers l'automatisation si les webhooks vous semblent excessifs pour votre situation.

Quelle que soit l'approche que vous choisissez, l'objectif est le même : réduire la gestion manuelle des tickets afin que votre équipe puisse se concentrer sur la résolution des problèmes des clients. Commencez par un webhook simple pour un cas d'utilisation, ou explorez l'automatisation basée sur l'IA, et développez à partir de là au fur et à mesure que vous voyez des résultats.