Webhook de conversation créée dans Zendesk Messaging : un guide d’implémentation complet

Les notifications en temps réel sont l’épine dorsale des flux de travail de support modernes. Lorsqu’un client démarre une conversation, vos systèmes doivent le savoir immédiatement, et non lorsque quelqu’un vérifie manuellement les mises à jour. Les webhooks comblent cette lacune.

Mais voici le problème avec Zendesk : ils ont deux systèmes de webhook complètement différents, et le webhook « conversation créée » fonctionne différemment de ce que la plupart des gens attendent. Ce guide dissipe la confusion et vous montre exactement comment configurer et utiliser les webhooks de conversation dans Zendesk, que vous construisiez des intégrations d’IA, synchronisiez des données avec votre CRM ou routiez des notifications vers Slack.

Qu’est-ce que le webhook de conversation créée dans Zendesk Messaging ?

Commençons par dissiper une idée fausse courante. Lorsque les gens recherchent « webhook de conversation créée dans Zendesk Messaging », ils pensent généralement à la plateforme de messagerie Sunshine Conversations (l’infrastructure qui alimente Zendesk Messaging). Mais l’événement « conversation créée » se trouve en réalité dans un système complètement différent.

Zendesk a deux architectures de webhook :

Les webhooks Zendesk standard gèrent les tickets, les utilisateurs, les organisations et, oui, les événements de conversation. Ceux-ci se trouvent dans le Centre d’administration sous Applications et intégrations.

Les webhooks de messagerie (Sunshine Conversations) gèrent les messages de chat en temps réel via la plateforme de messagerie. Ceux-ci sont configurés séparément et utilisent différents types d’événements.

L’événement conversation.created que vous recherchez ? Il fait partie du système de webhook standard, pas de la plateforme de messagerie. Cela déroute beaucoup de développeurs qui s’attendent à le trouver dans la documentation de la messagerie.

Alors, que fait réellement ce webhook ? Lorsqu’une nouvelle conversation démarre dans votre compte Zendesk, que ce soit à partir du Web Widget, du SDK mobile, de WhatsApp ou de tout autre canal, ce webhook se déclenche et envoie un payload à votre point de terminaison avec tous les détails de la conversation. Votre application peut alors réagir en temps réel : déclencher un agent d’IA, enregistrer dans votre entrepôt de données, envoyer une notification ou router la conversation en fonction du canal source.

Prérequis pour la configuration des webhooks de messagerie

Avant de commencer à configurer les webhooks, assurez-vous d’avoir :

• Un accès administrateur au Centre d’administration Zendesk : vous aurez besoin des autorisations pour créer des webhooks et gérer les intégrations
• Une URL de point de terminaison prête à recevoir les payloads : il doit s’agir d’une URL HTTPS accessible au public qui peut accepter les requêtes POST
• Une compréhension de base de la sécurité des webhooks : vous devrez vérifier les signatures pour vous assurer que les requêtes proviennent réellement de Zendesk
• Un plan pour gérer les nouvelles tentatives et les échecs : votre point de terminaison doit répondre dans les 12 secondes, sinon Zendesk réessayera

Une limitation importante à connaître : les comptes d’essai sont limités à 10 webhooks et 60 invocations par minute. Si vous testez sur un essai, planifiez en conséquence.

Comment créer un webhook de conversation dans Zendesk

Il existe deux façons de configurer votre webhook : via l’interface utilisateur du Centre d’administration ou via l’API. L’interface utilisateur est plus rapide pour les configurations ponctuelles, tandis que l’API fonctionne mieux si vous automatisez les déploiements ou gérez plusieurs environnements.

Utilisation du Centre d’administration

Étape 1 : Accéder à la section des webhooks

Accédez au Centre d’administration, puis cliquez sur Applications et intégrations dans la barre latérale. Sélectionnez Webhooks > Webhooks dans le sous-menu.

Étape 2 : Créer le webhook

Cliquez sur Créer un webhook et choisissez votre méthode de connexion. Pour les événements de conversation, sélectionnez Événements Zendesk (pas Déclencheur ou Automatisation).

Le choix de la méthode de connexion est permanent. Une fois que vous avez créé un webhook en tant que « Événements Zendesk », vous ne pouvez pas le convertir en webhook basé sur un déclencheur ultérieurement. Si vous avez besoin des deux types d’événements, créez des webhooks distincts.

Étape 3 : Configurer les paramètres du webhook

Remplissez la configuration de base :

• Nom et description : utilisez quelque chose de descriptif comme « Notifications de nouvelle conversation » afin que votre équipe sache ce qu’il fait
• URL du point de terminaison : votre point de terminaison HTTPS qui recevra les payloads
• Méthode de requête : POST (ceci est fixe pour les webhooks abonnés aux événements)
• Format de requête : JSON (également fixe pour les abonnements aux événements)

Étape 4 : Sélectionner l’événement de conversation créée

Dans la section des abonnements aux événements, sélectionnez zen:event-type:conversation.created dans la liste déroulante. Vous pouvez vous abonner à plusieurs événements si nécessaire (comme conversation.updated ou conversation.closed).

Étape 5 : Configurer l’authentification

Choisissez votre méthode d’authentification :

Pour la production, vous devez également activer la vérification de signature. Zendesk signe chaque requête avec HMAC SHA256, et vous pouvez vérifier la signature par rapport au secret de signature de votre webhook pour vous assurer que les requêtes sont légitimes.

Utilisation de l’API

Pour la configuration programmatique, utilisez l’API Webhooks :

curl -X POST https://{subdomain}.zendesk.com/api/v2/webhooks \
  -u {email_address}/token:{api_token} \
  -H "Content-Type:application/json" \
  -d '{
    "webhook": {
      "name": "Conversation Created Webhook",
      "status": "active",
      "endpoint": "https://your-endpoint.com/webhook",
      "http_method": "POST",
      "request_format": "json",
      "subscriptions": [
        "zen:event-type:conversation.created"
      ],
      "authentication": {
        "type": "bearer_token",
        "data": {
          "token": "YOUR_TOKEN"
        },
        "add_position": "header"
      }
    }
  }'

L’API renvoie un ID de webhook unique que vous utiliserez pour la surveillance et les mises à jour.

Comprendre le payload du webhook de conversation créée

Lorsqu’une conversation est créée, Zendesk envoie un payload JSON à votre point de terminaison. Voici ce à quoi vous pouvez vous attendre :

{
  "account_id": 21825834,
  "detail": {
    "id": "141"
  },
  "event": {
    "conversation_id": "67ab5f53a96f98663935c3f2",
    "created_at": "2025-02-11T14:32:05Z",
    "source_channel": "web",
    "participant_count": 1
  },
  "id": "01JQMQH83YNAKWSWJ8B1QH2NSC",
  "subject": "zen:ticket:141",
  "time": "2025-02-11T14:32:05.254571515Z",
  "type": "zen:event-type:conversation.created",
  "zendesk_event_version": "2022-11-06"
}

Champs clés auxquels prêter attention :

• detail.id : l’ID de ticket associé à cette conversation
• event.conversation_id : l’identifiant de conversation unique
• event.source_channel : l’origine de la conversation (web, whatsapp, facebook, etc.)
• type : le type d’événement qui a déclenché ce webhook

La structure du payload diffère des webhooks de messagerie (qui utilisent un tableau events imbriqué avec des types conversation:message). Les webhooks de conversation standard ont une structure plus plate axée sur le cycle de vie de la conversation plutôt que sur les messages individuels.

Authentification et meilleures pratiques de sécurité

Les webhooks ne sont aussi sécurisés que votre processus de vérification. Étant donné que votre point de terminaison est accessible au public, vous devez vérifier que les requêtes proviennent réellement de Zendesk.

Vérification de signature

Chaque requête de webhook inclut deux en-têtes :

• X-Zendesk-Webhook-Signature : la signature HMAC SHA256
• X-Zendesk-Webhook-Signature-Timestamp : l’horodatage Unix du moment où la requête a été envoyée

Pour vérifier une requête :

1. Extraire les deux en-têtes de la requête entrante
2. Concaténer l’horodatage et le corps de la requête (horodatage + « . » + corps)
3. Générer un hachage HMAC SHA256 en utilisant le secret de signature de votre webhook
4. Encoder le résultat en Base64
5. Comparer à l’en-tête de signature

L’algorithme est le suivant : base64(HMACSHA256(TIMESTAMP + "." + BODY))

Vous pouvez trouver votre secret de signature dans le Centre d’administration en cliquant sur « Révéler le secret » sur la page des paramètres de votre webhook. Pour les tests avant de créer le webhook, utilisez ce secret de test statique : dGhpc19zZWNyZXRfaXNfZm9yX3Rlc3Rpbmdfb25seQ==

Exigence HTTPS

Utilisez toujours des points de terminaison HTTPS pour les webhooks de production. Outre les avantages en matière de sécurité, certaines fonctionnalités comme les en-têtes personnalisés et certaines méthodes d’authentification ne fonctionnent qu’avec HTTPS.

Idempotence

Zendesk fait de son mieux pour livrer les webhooks exactement une fois, mais ils ne peuvent pas le garantir. Votre point de terminaison peut recevoir le même événement de conversation créée plusieurs fois, en particulier lors des nouvelles tentatives ou si le disjoncteur s’active.

Concevez votre gestionnaire pour qu’il soit idempotent : vérifiez si vous avez déjà traité un ID de conversation avant de prendre des mesures. Cela empêche les notifications en double, les entrées CRM en double ou le déclenchement de la même automatisation deux fois.

Gestion des événements de webhook dans votre application

Voici un modèle de base pour la gestion des webhooks de conversation dans Node.js :

const crypto = require('crypto');

app.post('/webhook', (req, res) => {
  // Vérifier la signature
  const signature = req.headers['x-zendesk-webhook-signature'];
  const timestamp = req.headers['x-zendesk-webhook-signature-timestamp'];
  const payload = JSON.stringify(req.body);

  const expectedSignature = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(`${timestamp}.${payload}`)
    .digest('base64');

  if (signature !== expectedSignature) {
    return res.status(401).send('Invalid signature');
  }

  // Traiter l’événement de manière asynchrone
  const event = req.body;

  if (event.type === 'zen:event-type:conversation.created') {
    // Mettre en file d’attente pour le traitement : ne pas bloquer la réponse
    processConversationCreated(event);
  }

  // Répondre rapidement pour éviter les nouvelles tentatives
  res.status(200).send('OK');
});

Les principes clés :

• Vérifier la signature avant le traitement
• Répondre avec un code 200 OK rapidement (dans les 12 secondes)
• Traiter l’événement de manière asynchrone : ne laissez pas votre logique métier bloquer la réponse HTTP
• Gérer les événements en double avec élégance

Modèles d’intégration courants

Déclenchement d’agent d’IA : lorsqu’une conversation est créée, vérifiez si un agent d’IA doit la gérer en premier avant de la router vers des agents humains. Vérifiez le canal source, l’heure de la journée ou le segment de clientèle pour prendre la décision de routage.

Journalisation CRM : enregistrez le début de la conversation dans votre CRM pour la création de rapports et l’analyse. Incluez la source du canal pour comprendre d’où les clients vous contactent.

Notifications Slack : envoyez une notification à un canal Slack lorsque des conversations à haute priorité démarrent, ou routez différents canaux vers différents canaux Slack en fonction de la source.

Si vous créez des intégrations d’IA et que vous souhaitez éviter complètement le développement de webhook, eesel AI se connecte directement à Zendesk et gère le traitement des conversations sans nécessiter de gestionnaires de webhook personnalisés. Nous écoutons les événements de conversation et générons automatiquement des réponses contextuelles basées sur votre base de connaissances.

Dépannage des problèmes courants de webhook

Même les webhooks correctement configurés peuvent échouer. Voici comment diagnostiquer et résoudre les problèmes les plus courants :

Erreurs de connexion

Activation du disjoncteur

Si votre point de terminaison commence à renvoyer des erreurs, le disjoncteur de Zendesk s’activera pour protéger votre serveur contre la surcharge. Il se déclenche lorsqu’un pourcentage important de requêtes échoue dans un court laps de temps.

Lorsqu’il est activé, les webhooks s’interrompent brièvement. Après la pause, Zendesk réessaie. Si cette requête échoue, le disjoncteur déclenche une autre pause. Ce cycle se poursuit jusqu’à ce qu’une requête réussisse.

Remarque : Le disjoncteur ne s’active généralement pas sur les webhooks à faible volume, de sorte que les petits environnements de test sont généralement à l’abri des verrouillages accidentels.

Conseils de débogage

• Vérifiez les journaux d’activité des webhooks dans le Centre d’administration (conservés pendant 7 jours)
• Filtrez par statut pour voir les invocations ayant échoué : ajoutez ?filter[status]=failed à la requête API
• Utilisez des outils comme ngrok ou Hookdeck pour inspecter les payloads réels pendant le développement
• Vérifiez que le format de votre payload correspond à ce que votre point de terminaison attend : la structure diffère entre les webhooks standard et les webhooks de messagerie

Référence du comportement de nouvelle tentative

Rationaliser les intégrations de webhook avec eesel AI

La création de gestionnaires de webhook personnalisés prend beaucoup de temps de développement. Vous devez gérer la vérification de signature, la logique de nouvelle tentative, l’idempotence et la gestion des erreurs avant même d’arriver à votre logique métier réelle. Ensuite, il y a la maintenance continue : la surveillance, la journalisation et la mise à jour à mesure que les API de Zendesk évoluent.

Si votre objectif est l’automatisation du support basée sur l’IA plutôt que l’infrastructure de webhook, il existe un chemin plus simple.

eesel AI se connecte directement à votre compte Zendesk et gère toute la complexité du webhook pour vous :

• Traitement des conversations en temps réel : nous ingérons les événements de ticket et de messagerie au fur et à mesure qu’ils se produisent, sans qu’aucun développement de webhook ne soit requis de votre côté
• Réponses d’IA contextuelles : notre système utilise votre base de connaissances, vos tickets passés et vos articles du centre d’aide pour générer des réponses qui correspondent à la voix de votre marque
• Actions au-delà du texte : recherchez des commandes dans Shopify, traitez les remboursements, mettez à jour les champs de ticket, et plus encore, le tout configuré via des instructions en langage naturel plutôt que du code
• Déploiement progressif : commencez par le mode copilote où les agents examinent les brouillons d’IA, puis passez aux réponses autonomes au fur et à mesure que vous gagnez en confiance

La configuration prend quelques minutes, pas des jours. Connectez votre compte Zendesk, formez-vous sur vos données existantes et choisissez votre mode. Vous pouvez exécuter des simulations sur les tickets passés pour vérifier la qualité avant de passer en direct.

Les déploiements matures utilisant eesel AI atteignent jusqu’à 81 % de résolution autonome avec des périodes de récupération typiques inférieures à 2 mois. Si vous envisagez de créer des gestionnaires de webhook personnalisés pour l’intégration de l’IA, essayez eesel AI gratuitement pendant 7 jours et voyez s’il couvre votre cas d’utilisation.

Commencez à créer avec les webhooks de conversation Zendesk dès aujourd’hui

Le webhook de conversation créée est un outil puissant pour l’automatisation du support en temps réel. Que vous déclenchiez des agents d’IA, synchronisiez des données avec des systèmes externes ou routiez des notifications, il est essentiel de comprendre comment configurer et gérer correctement ces webhooks.

N’oubliez pas la distinction clé : les webhooks standard gèrent les événements du cycle de vie des conversations (créée, mise à jour, fermée), tandis que les webhooks de messagerie gèrent le flux de messages en temps réel. L’événement conversation.created se trouve dans le système de webhook standard, et c’est votre point d’entrée pour réagir aux nouvelles conversations client sur tous les canaux.

Commencez par l’interface utilisateur du Centre d’administration pour vous familiariser avec la structure du payload, puis passez à l’API lorsque vous êtes prêt à automatiser. Activez la vérification de signature dès le premier jour, concevez pour l’idempotence et répondez rapidement pour éviter les tempêtes de nouvelles tentatives.

Pour les équipes qui créent un support basé sur l’IA sans les frais généraux d’infrastructure, eesel AI élimine le besoin de gestionnaires de webhook personnalisés tout en fournissant des réponses contextuelles basées sur les connaissances. Quoi qu’il en soit, la sensibilisation aux conversations en temps réel est désormais à portée de main.