Comment configurer les webhooks de messagerie Zendesk : Un guide complet

Les webhooks transforment votre instance Zendesk en un moteur de notification en temps réel. Au lieu de vérifier manuellement les mises à jour, les webhooks poussent les données vers des systèmes externes dès qu'un événement se produit, qu'il s'agisse de la création d'un ticket, de l'arrivée d'un message ou de la mise à jour du profil d'un utilisateur.

Les applications pratiques vont des alertes Slack pour les tickets urgents à l'alimentation d'outils d'IA comme eesel AI avec des données client en direct. Ce guide détaille les deux types de webhooks Zendesk (basés sur les événements et basés sur les déclencheurs), couvre la configuration spécifique à la messagerie via l'API Conversations et explique les méthodes d'authentification pour que vos intégrations restent sécurisées.

À la fin de ce guide, vous disposerez de webhooks fonctionnels connectés à vos flux de travail de support.

Que sont les webhooks Zendesk et comment fonctionnent-ils ?

Un webhook envoie une requête HTTP à une URL spécifiée chaque fois qu'un événement survient dans Zendesk Support, Guide, Gather ou Messaging. Considérez cela comme une notification push en temps réel pour vos systèmes. Lorsqu'un utilisateur est supprimé ou qu'un nouveau ticket arrive, Zendesk contacte votre point de terminaison (endpoint) avec les données pertinentes.

Les cas d'utilisation courants incluent :

• Alertes Slack ou Teams pour les tickets de haute priorité
• Synchronisation CRM pour maintenir les dossiers clients à jour
• Notifications SMS via des services comme Twilio ou 8x8
• Intégrations d'IA où des outils traitent les messages entrants et génèrent des réponses

Deux méthodes de connexion aux webhooks

Cette distinction est importante car vous ne pouvez pas les mélanger. Une fois que vous avez créé un webhook avec une méthode, vous ne pouvez plus la changer.

Les webhooks d'abonnement aux événements répondent aux événements Zendesk tels que la création d'utilisateurs, les mises à jour d'organisations, la publication d'articles du centre d'aide ou l'activité de messagerie. Ceux-ci utilisent toujours POST avec une charge utile (payload) JSON, et Zendesk contrôle la structure de cette charge utile.

Les webhooks de déclenchement ou d'automatisation se connectent à vos règles de gestion Support. Lorsqu'un ticket remplit certaines conditions, le webhook se déclenche. Vous avez un contrôle total sur la méthode HTTP (GET, POST, PUT, PATCH, DELETE) et pouvez personnaliser le format de la requête (JSON, XML ou encodage de formulaire). La charge utile utilise des espaces réservés (placeholders) comme {{ticket.id}} que Zendesk remplit au moment de l'exécution.

Type de connexion	Déclenché par	Méthodes HTTP	Contrôle de la charge utile
Événements Zendesk	Activité utilisateur, org, messagerie, centre d'aide	POST uniquement	Défini par Zendesk
Déclencheur/Automatisation	Conditions de ticket	Toutes les méthodes	Défini par l'utilisateur avec placeholders

Comment configurer les webhooks Zendesk pour la messagerie et les déclencheurs

La configuration des webhooks nécessite un accès administrateur ou un rôle personnalisé avec les permissions de webhook. Voici le processus étape par étape.

Étape 1 : Accéder à la section des webhooks dans le Centre d'administration

Naviguez vers le Centre d'administration, puis cliquez sur Applications et intégrations dans la barre latérale. Sélectionnez Webhooks dans le sous-menu. Vous verrez une liste des webhooks existants (le cas échéant) et un bouton pour en créer de nouveaux.

Les comptes d'essai ont des limites : un maximum de 10 webhooks et 60 appels par minute. Les forfaits payants suppriment ces restrictions.

Étape 2 : Créer un nouveau webhook

Cliquez sur « Créer un webhook » et choisissez votre méthode de connexion :

• Événements Zendesk : Sélectionnez ceci pour l'activité de messagerie, d'utilisateur, d'organisation ou de centre d'aide. Vous choisirez des événements spécifiques auxquels vous abonner.
• Déclencheur ou automatisation : Sélectionnez ceci pour l'activité basée sur les tickets où vous souhaitez des charges utiles personnalisées.

Ce choix est permanent. Vous ne pourrez pas convertir un webhook de déclenchement en un webhook d'abonnement aux événements plus tard, alors choisissez bien dès le départ.

Étape 3 : Configurer les paramètres du webhook

Remplissez la configuration de base :

• Nom et Description : Utilisez des noms descriptifs comme « Alertes Slack tickets urgents » ou « Sync client CRM » pour que votre équipe sache ce que fait chaque webhook.
• URL du point de terminaison : L'URL de votre serveur de réception. Le HTTPS est fortement recommandé pour la sécurité.
• Méthode de requête : Pour les webhooks d'abonnement aux événements, c'est toujours POST. Pour les webhooks de déclenchement, choisissez en fonction de ce que votre point de terminaison attend.
• Format de la requête : JSON, XML ou encodage de formulaire (webhooks de déclenchement uniquement).

Vous pouvez également ajouter jusqu'à 5 en-têtes personnalisés pour les points de terminaison HTTPS. Les noms d'en-tête acceptent les caractères alphanumériques et certains symboles, avec une limite de 128 caractères. Les valeurs peuvent aller jusqu'à 1 000 caractères.

Étape 4 : Configurer l'authentification

Choisissez la méthode d'authentification requise par votre point de terminaison :

Méthode	Quand l'utiliser	Configuration
Aucune	Tests ou points de terminaison avec liste blanche d'IP	Aucun identifiant requis
Clé API	Services tiers avec authentification par en-tête	Paire nom/valeur dans l'en-tête
Basic Auth	Services internes ou appels API Zendesk	Nom d'utilisateur et mot de passe (utilisez le format {email}/token:{api_token} pour Zendesk)
Bearer Token	Services compatibles OAuth	Jeton d'accès dans l'en-tête Authorization

Toutes les méthodes d'authentification doivent utiliser HTTPS. Ne placez jamais d'identifiants sensibles dans des en-têtes personnalisés — utilisez plutôt les options d'authentification intégrées.

Étape 5 : Connecter à un déclencheur ou une automatisation

Pour les webhooks basés sur les déclencheurs, vous devez les connecter à une règle de gestion :

1. Allez dans le Centre d'administration, puis Objets et règles, puis Règles de gestion, puis Déclencheurs.
2. Créez un nouveau déclencheur ou modifiez-en un existant.
3. Sous Actions, cliquez sur « Ajouter une action ».
4. Sélectionnez « Notifier le webhook » et choisissez votre webhook dans la liste déroulante.
5. Définissez la charge utile JSON en utilisant des espaces réservés (placeholders). Par exemple :

{
  "ticket_id": "{{ticket.id}}",
  "subject": "{{ticket.title}}",
  "status": "{{ticket.status}}",
  "requester_email": "{{ticket.requester.email}}"
}

Zendesk remplace ces placeholders par les valeurs réelles avant d'envoyer la requête. La charge utile doit être inférieure à 256 Ko.

Étape 6 : Tester votre webhook

Avant de passer en direct, utilisez la fonction de test intégrée :

1. Ouvrez votre webhook depuis la page Webhooks.
2. Cliquez sur « Tester le webhook ».
3. Sélectionnez un événement type ou saisissez des données de test.
4. Cliquez sur « Envoyer le test » et vérifiez la réponse.

Un code d'état 200 signifie que le test a réussi. Si vous obtenez des erreurs, vérifiez les journaux de votre point de terminaison. Les problèmes courants incluent des URL erronées, une authentification invalide ou des charges utiles mal formées.

Pour le développement local, des outils comme ngrok ou Hookdeck créent des URL publiques qui pointent vers votre serveur local. Cela vous permet de tester les webhooks sans déploiement en production.

Configuration des webhooks de messagerie Zendesk avec l'API Conversations

La plateforme de messagerie de Zendesk (Sunshine Conversations) possède son propre système de webhooks pour la messagerie en temps réel. Il est distinct des webhooks standard et conçu spécifiquement pour les interactions par chat.

Créer un webhook de messagerie

Les webhooks de messagerie appartiennent à une intégration. Vous pouvez en créer un via le Centre d'administration ou l'API :

1. Créez une intégration personnalisée dans le Centre d'administration sous Applications et intégrations.
2. Enregistrez l'URL cible de votre webhook.
3. Configurez les événements à recevoir (comme conversation:message).
4. Définissez des options supplémentaires comme includeFullUser et includeFullSource pour des charges utiles plus détaillées.

Événements clés des webhooks pour la messagerie

La plateforme de messagerie prend en charge plusieurs types d'événements :

Événement	Description
conversation:message	Tout message envoyé par l'utilisateur ou l'entreprise
conversation:read	L'utilisateur a lu les messages
conversation:postback	L'utilisateur a cliqué sur un bouton de postback
passthrough:messaging	Données de transfert spécifiques au canal

Comprendre la charge utile du webhook

Lorsqu'un message arrive, la charge utile du webhook inclut tout ce dont vous avez besoin pour répondre de manière appropriée :

{
  "account_id": 21825834,
  "detail": {
    "id": "141"
  },
  "event": {
    "actor": {
      "id": "zd:answerBot",
      "name": "Support Bot",
      "type": "system"
    },
    "conversation_id": "67ab5f53a96f98663935c3f2",
    "message": {
      "body": "Bonjour. Comment puis-je vous aider aujourd'hui ?",
      "id": "67ab5f55155becd183e284cb"
    }
  },
  "type": "zen:event-type:messaging_ticket.message_added"
}

Les champs clés incluent l'ID de la conversation (pour suivre le fil), le contenu du message et les informations sur l'acteur (si le message provient d'un utilisateur, d'un agent ou du système). Ces données permettent aux outils d'IA d'analyser les messages entrants et de générer automatiquement des réponses contextuelles.

Méthodes d'authentification et meilleures pratiques de sécurité pour la configuration des webhooks Zendesk

La sécurité est primordiale. Un point de terminaison de webhook non sécurisé peut laisser fuiter des données client ou permettre à des acteurs malveillants d'injecter de fausses requêtes.

Choisir la bonne méthode d'authentification

Méthode	Idéal pour	Notes
Clé API	Services tiers	Authentification simple par en-tête
Basic Auth	Services internes, appels API Zendesk	Utilisez le format {email}/token:{token}
Bearer Token	Services compatibles OAuth	Standard pour les API modernes
Aucune	Tests uniquement	Ne jamais utiliser en production

Vérification des signatures de webhook

Pour les intégrations critiques en matière de sécurité, Zendesk propose la vérification de signature. Chaque requête comprend deux en-têtes :

• X-Zendesk-Webhook-Signature : La signature principale
• X-Zendesk-Webhook-Signature-Timestamp : Horodatage pour la vérification

Pour vérifier :

1. Extrayez les deux en-têtes de la requête entrante.
2. Concaténez l'horodatage et le corps de la requête.
3. Créez un hachage HMAC SHA256 en utilisant le secret de signature de votre webhook.
4. Encodez le résultat en Base64.
5. Comparez-le à l'en-tête de signature.

L'algorithme ressemble à ceci : base64(HMACSHA256(TIMESTAMP + BODY))

Si les signatures correspondent, la requête est authentique. Sinon, rejetez-la.

Vous pouvez trouver votre secret de signature dans le Centre d'administration sous les paramètres de votre webhook (cliquez sur « Révéler le secret »). Pour tester avant la création du webhook, utilisez le secret de test statique : dGhpc19zZWNyZXRfaXNfZm9yX3Rlc3Rpbmdfb25seQ==

Recommandations de sécurité

• Utilisez toujours des points de terminaison HTTPS.
• Implémentez la vérification de signature pour les webhooks en production.
• Rendez vos gestionnaires de webhooks idempotents (Zendesk peut réessayer ou envoyer des doublons).
• Surveillez les journaux d'activité des webhooks pour détecter les échecs de livraison.
• Utilisez la gestion des secrets plutôt que des identifiants codés en dur.

Dépannage des problèmes courants de configuration des webhooks de messagerie Zendesk

Même les webhooks bien configurés peuvent échouer. Voici comment diagnostiquer et résoudre les problèmes les plus fréquents.

Erreurs de connexion

Erreur	Cause	Solution
401/403	Identifiants invalides	Vérifiez la clé API ou le jeton, assurez-vous que la méthode d'auth correspond aux attentes du point de terminaison
404	URL de point de terminaison erronée	Confirmez que le chemin de l'URL et le domaine sont corrects
Timeout	Point de terminaison trop lent	Répondez en moins de 12 secondes, traitez les données de manière asynchrone
Erreur SSL	Problème de certificat	Utilisez un certificat valide signé par une autorité de certification (Let's Encrypt fonctionne très bien)

Activation du coupe-circuit (circuit breaker)

Zendesk protège les points de terminaison contre la surcharge. Le coupe-circuit se déclenche lorsque :

• 70 % des requêtes échouent en 5 minutes, OU
• Plus de 1 000 erreurs surviennent en 5 minutes.

Lorsqu'il est déclenché, les webhooks s'interrompent pendant 5 secondes. Après la pause, Zendesk réessaie. Une requête réussie réinitialise le circuit ; un échec déclenche une autre pause de 5 secondes. Ce cycle continue jusqu'à ce que votre point de terminaison se rétablisse.

Le coupe-circuit ne se déclenchera pas si moins de 100 requêtes surviennent en 5 minutes, donc les webhooks à faible volume sont généralement à l'abri des blocages accidentels.

Conseils de débogage

• Consultez le Centre d'administration sous Webhooks pour les journaux d'activité (conservés 7 jours).
• Filtrez les journaux par statut : filter[status]=failed.
• Utilisez des outils de surveillance de requêtes pour inspecter les charges utiles réelles.
• Vérifiez que le format de la charge utile correspond à ce que votre point de terminaison attend.
• Testez avec des outils comme Postman ou curl pour isoler les problèmes.

Comportement de nouvelle tentative (retry)

Réponse	Comportement
HTTP 409	Réessaie jusqu'à 3 fois
HTTP 429/503 avec retry-after < 60s	Réessaie selon l'en-tête
Timeout (>12 secondes)	Réessaie jusqu'à 5 fois
Autres erreurs	Pas de nouvelle tentative automatique

Zendesk fait de son mieux pour livrer les webhooks une fois, mais des doublons ou des événements manqués sont possibles. Concevez vos gestionnaires pour qu'ils soient idempotents.

Simplifiez les intégrations de webhooks avec eesel AI

Configurer des webhooks n'est que la première étape. Construire des réponses intelligentes nécessite un développement supplémentaire : analyse des charges utiles, intégration avec votre base de connaissances, rédaction de réponses contextuelles et gestion des cas particuliers. C'est là que nous intervenons.

eesel AI se connecte à votre Zendesk et gère la complexité pour vous :

• Traitement en temps réel : Nous ingérons les événements de tickets et de messagerie au fur et à mesure qu'ils surviennent — aucun développement de webhook n'est requis de votre côté.
• Réponses contextuelles : Notre IA utilise votre base de connaissances, vos anciens tickets et votre centre d'aide pour générer des réponses qui correspondent à l'image de votre marque.
• Actions au-delà des réponses : Recherchez des commandes dans Shopify, traitez des remboursements, mettez à jour des champs de tickets, et plus encore — le tout configuré sans code.
• Déploiement progressif : Commencez par le mode copilot (brouillon pour révision) avant de passer aux réponses autonomes.

Premiers pas avec eesel AI pour Zendesk

La configuration ne prend que quelques minutes :

1. Connectez votre compte Zendesk via notre tableau de bord.
2. Entraînez l'IA sur vos données existantes (anciens tickets, articles du centre d'aide, macros, documents connectés).
3. Choisissez votre mode : copilot (les agents révisent les brouillons de l'IA) ou autonome (l'IA répond directement).
4. Lancez des simulations sur d'anciens tickets pour vérifier la qualité avant la mise en ligne.

Cela élimine le besoin de construire des gestionnaires de webhooks personnalisés tout en offrant une automatisation du support alimentée par l'IA. Les déploiements matures atteignent jusqu'à 81 % de résolution autonome avec des périodes de retour sur investissement inférieures à 2 mois.

Forfait	Mensuel	Annuel	Interactions/mois
Team	299 $	239 $/mois	1 000
Business	799 $	639 $/mois	3 000
Custom	Contactez-nous	Sur mesure	Illimité

Le forfait Business inclut l'Agent IA pour les réponses autonomes, l'entraînement sur les anciens tickets et des capacités de simulation en masse. Essayez eesel AI gratuitement pendant 7 jours.