Comment configurer les webhooks de message livré de Zendesk Messaging

Les webhooks transforment votre Zendesk en un moteur de notification en temps réel. Au lieu d'interroger pour obtenir des mises à jour, les webhooks envoient des données à vos systèmes dès que quelque chose se produit. Pour la messagerie en particulier, les webhooks de livraison vous permettent de suivre si les messages atteignent réellement vos clients. Pas seulement remis à WhatsApp ou Twilio, mais réellement livrés.

C'est important car « envoyé » et « livré » sont deux choses différentes. Un message peut quitter Zendesk, échouer au niveau de l'opérateur, et vous ne le sauriez jamais sans le suivi de la livraison. Ou il pourrait rester non livré parce que le téléphone d'un client est hors ligne. Les webhooks de livraison vous donnent une visibilité sur le cycle de vie complet du message.

Dans ce guide, vous apprendrez comment configurer les webhooks de livraison de messages Zendesk à partir de zéro. Nous couvrirons les trois types d'événements de livraison, parcourrons la configuration étape par étape et fournirons du code fonctionnel que vous pourrez adapter à votre propre implémentation.

Ce dont vous aurez besoin

Avant de plonger, assurez-vous d'avoir :

• Un compte Zendesk avec un accès administrateur (la configuration des webhooks nécessite des permissions d'administrateur)
• Un endpoint HTTPS pour recevoir les payloads de webhook (un serveur de développement fonctionne bien pour les tests)
• Une familiarité de base avec les concepts JSON et HTTP
• Optionnellement : un outil comme Postman ou curl pour les tests

Si vous construisez cela pour la production, vous voudrez également réfléchir à l'authentification, à la gestion des erreurs et à l'idempotence. Nous aborderons tous ces points.

Comprendre les événements de livraison de messages Zendesk

La plateforme de messagerie de Zendesk envoie trois types d'événements de livraison. Chacun vous indique quelque chose de différent sur l'état de votre message.

Les trois types d'événements de livraison

Voici comment le flux fonctionne. Lorsque vous envoyez un message, il atteint d'abord l'API du canal. Si cette API accepte le message, vous obtenez un événement delivery:channel. Pour certains canaux (comme WhatsApp ou SMS via Twilio), vous pourriez plus tard obtenir un événement delivery:user confirmant que le message a atteint l'appareil. Si quelque chose échoue en cours de route, vous obtenez delivery:failure avec des informations d'erreur spécifiques.

Le flag isFinalEvent vous indique si d'autres événements sont à venir. Lorsque isFinalEvent: true, c'est le dernier webhook que vous recevrez pour ce message. Lorsque false, le canal prend en charge la confirmation de livraison au niveau de l'utilisateur, alors attendez-vous à un suivi.

La prise en charge des canaux varie

Tous les canaux ne peuvent pas confirmer la livraison à l'utilisateur. Certains confirment seulement qu'ils ont reçu le message de Zendesk. Voici la répartition :

Canaux avec confirmation de livraison complète (canal + utilisateur) :

• WhatsApp
• Twilio SMS
• MessageBird
• iOS SDK, Android SDK, Unity SDK, Web Widget

Canaux avec livraison de canal seulement :

• Facebook Messenger
• Instagram
• LINE
• Telegram
• Viber
• WeChat
• X (Twitter)
• Apple Messages for Business

Pour les canaux sans confirmation d'utilisateur, l'événement delivery:channel aura isFinalEvent: true. C'est votre signal qu'aucune autre mise à jour n'est à venir.

Pourquoi c'est important pour votre implémentation

Si vous construisez des analyses par-dessus ces webhooks, vous voudrez tenir compte de cette variation. Une métrique « livré » signifie différentes choses selon le canal. Pour WhatsApp, c'est une confirmation au niveau de l'appareil. Pour Facebook Messenger, cela signifie simplement que l'API de Facebook a accepté le message.

Étape 1 : Créer un webhook dans le Centre d'administration Zendesk

Parcourons la création de votre premier webhook de livraison.

D'abord, naviguez vers Centre d'administration > Applications et intégrations > Webhooks. Si vous ne voyez pas l'option Webhooks, vérifiez que votre rôle a les permissions appropriées. Apprenez-en davantage dans la documentation des webhooks Zendesk.

Cliquez sur Créer un webhook. Vous verrez un formulaire avec plusieurs champs :

Nom : Donnez-lui quelque chose de descriptif comme « Suivi de la livraison des messages » ou « Événements de livraison en production ».

URL de l'endpoint : C'est là que Zendesk POSTera les payloads de webhook. Pour le développement, vous pouvez utiliser un outil comme ngrok pour exposer un serveur local. Pour la production, cela devrait être une URL HTTPS sur votre infrastructure.

Méthode HTTP : Sélectionnez POST. Les événements de livraison utilisent toujours POST.

Format de requête : Sélectionnez JSON.

Ne sauvegardez pas encore. Nous configurerons les abonnements aux événements et l'authentification dans les prochaines étapes.

Étape 2 : S'abonner aux événements de livraison

Dans le formulaire de création de webhook, trouvez la section Abonnements aux événements. C'est là que vous spécifiez quels événements devraient déclencher votre webhook.

Pour le suivi de la livraison des messages, abonnez-vous à ces trois événements :

1. conversation:message:delivery:channel
2. conversation:message:delivery:user
3. conversation:message:delivery:failure

Vous pouvez vous abonner à des événements supplémentaires si nécessaire (comme conversation:message pour tous les messages), mais pour le suivi de la livraison spécifiquement, ce sont ces trois-là que vous voulez.

Options de filtrage des événements :

Si votre intégration fait partie du commutateur, vous pouvez contrôler si vous recevez des événements pour les conversations que vous ne gérez pas activement. Le paramètre deliverStandbyEvents filtre cela. La plupart des intégrations définissent cela à false pour ne recevoir que les événements pour les conversations actives.

Sauvegardez le webhook. Zendesk lui attribuera un ID unique (commençant par 01). Copiez cet ID. Vous en aurez besoin pour les tests et pour la connexion aux déclencheurs si vous suivez cette voie.

Étape 3 : Configurer l'authentification du webhook

Les webhooks sans authentification sont un risque de sécurité. Quiconque découvre l'URL de votre endpoint pourrait envoyer de faux événements. Zendesk prend en charge plusieurs méthodes d'authentification.

Options d'authentification disponibles

Pour la plupart des implémentations, l'authentification par clé API trouve le juste équilibre entre sécurité et simplicité.

Configuration dans Zendesk

Dans le formulaire de webhook, développez la section Authentification. Sélectionnez votre méthode préférée et entrez les informations d'identification :

• Pour la clé API : spécifiez le nom de l'en-tête (par exemple, X-API-Key) et la valeur de la clé
• Pour le jeton Bearer : entrez le jeton que Zendesk devrait inclure
• Pour l'authentification de base : fournissez le nom d'utilisateur et le mot de passe

Vérification des signatures de webhook

Zendesk peut signer les webhooks en utilisant HMAC-SHA256. Cela vous permet de vérifier que les payloads proviennent réellement de Zendesk, et non d'un attaquant. Consultez la documentation de signature des webhooks Zendesk pour des conseils d'implémentation détaillés.

Pour activer cela, vous devrez :

1. Générer un secret de signature (Zendesk le fournit lorsque vous activez la signature)
2. Vérifier l'en-tête X-Zendesk-Webhook-Signature dans votre endpoint
3. Calculer le HMAC-SHA256 du payload en utilisant votre secret
4. Le comparer à l'en-tête de signature

Voici un exemple simple en Node.js :

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('base64');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Étape 4 : Construire votre endpoint de webhook

Maintenant, passons à la partie amusante : construire l'endpoint qui reçoit ces webhooks.

Exigences de base

Votre endpoint doit :

• Utiliser HTTPS (Zendesk rejette les URL HTTP)
• Répondre dans les 10 secondes
• Retourner un code d'état 2xx pour un traitement réussi
• Gérer les événements en double avec élégance (idempotence)

Exemple de récepteur de webhook (Node.js/Express)

Voici un endpoint minimal mais prêt pour la production :

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhooks/zendesk-delivery', (req, res) => {
  // Acknowledge receipt immediately
  res.status(200).send('OK');

  // Process events asynchronously
  const events = req.body.events || [];

  for (const event of events) {
    handleDeliveryEvent(event);
  }
});

function handleDeliveryEvent(event) {
  const { type, payload } = event;

  switch (type) {
    case 'conversation:message:delivery:channel':
      console.log(`Message ${payload.message.id} delivered to ${payload.destination.type}`);
      break;

    case 'conversation:message:delivery:user':
      console.log(`Message ${payload.message.id} reached user`);
      break;

    case 'conversation:message:delivery:failure':
      console.error(`Message ${payload.message.id} failed:`, payload.error);
      break;
  }
}

app.listen(3000, () => {
  console.log('Webhook endpoint listening on port 3000');
});

Les points clés que cet exemple fait :

1. Répond immédiatement (200 OK) avant le traitement
2. Traite les événements de manière asynchrone
3. Gère chaque type d'événement séparément
4. Extrait les ID pertinents pour la journalisation/le débogage

Gestion des nouvelles tentatives et de l'idempotence

Zendesk relance les webhooks échoués (réponses 4xx/5xx, délais d'attente) jusqu'à 3 à 5 fois selon l'erreur. Cela signifie que votre endpoint pourrait recevoir le même événement plusieurs fois.

Pour gérer cela, implémentez l'idempotence :

const processedEvents = new Set(); // Use Redis in production

function handleDeliveryEvent(event) {
  if (processedEvents.has(event.id)) {
    console.log(`Skipping duplicate event: ${event.id}`);
    return;
  }

  // Process the event...

  processedEvents.add(event.id);
}

En production, utilisez Redis ou une base de données pour suivre les ID d'événements traités avec TTL (time to live) afin que la fenêtre de déduplication corresponde au comportement de nouvelle tentative de Zendesk.

Étape 5 : Comprendre le payload du webhook de livraison

Décomposons ce qui arrive réellement dans ces webhooks.

Structure de payload commune

Tous les événements de livraison partagent cette structure d'encapsulation :

{
  "app": {
    "id": "5fb29b20fee5422428712475"
  },
  "webhook": {
    "id": "5ff5e98b0d0c6d8925594923",
    "version": "v2"
  },
  "events": [
    {
      "id": "5ff7595eafcaab0a685ff889",
      "createdAt": "2021-01-07T18:56:30.666Z",
      "type": "conversation:message:delivery:channel",
      "payload": {
        "conversation": { "id": "2d4fd3d00715d1e64611e248" },
        "user": { "id": "71268330a47f5c4b541fce46" },
        "destination": {
          "type": "whatsapp",
          "integrationId": "5ff75853b1c3000a6ad4f7f5"
        },
        "message": { "id": "5ff7595eb1c3000a6ad4f7fb" },
        "isFinalEvent": false,
        "externalMessages": [
          { "id": "wamid.HBgNNTUxQTk4MDUz5Tg4MRU..." }
        ]
      }
    }
  ]
}

Champs clés expliqués

Spécificités de l'événement d'échec

Lorsque la livraison échoue, le payload inclut un objet d'erreur :

{
  "error": {
    "code": "bad_request",
    "message": "Message failed to send because more than 24 hours have passed since the customer last replied.",
    "underlyingError": {
      "errors": [{
        "code": 131047,
        "title": "Re-engagement message",
        "message": "Re-engagement message"
      }]
    }
  }
}

Le champ underlyingError contient l'erreur brute de l'API du canal. C'est inestimable pour le débogage. Les codes d'erreur de WhatsApp, par exemple, vous indiquent exactement pourquoi un message a été rejeté.

Étape 6 : Tester votre implémentation de webhook

Avant de passer en direct, vous devez vérifier que tout fonctionne.

Utilisation du testeur de webhook de Zendesk

Dans la page de configuration du webhook, cliquez sur Tester le webhook. Zendesk enverra un payload de test à votre endpoint et vous montrera la réponse. C'est utile pour vérifier la connectivité et l'authentification.

Cependant, le payload de test est générique. Ce ne sera pas un véritable événement de livraison. Pour des tests réalistes, vous devez déclencher des flux de messages réels.

Tester avec de vrais messages

1. Envoyez un message de test via Zendesk Messaging
2. Vérifiez les journaux de votre endpoint pour les webhooks entrants
3. Vérifiez que la structure du payload correspond aux attentes
4. Confirmez que votre logique de gestion des événements traite correctement chaque type

Pour les canaux qui prennent en charge la livraison à l'utilisateur (comme WhatsApp), vous pouvez vérifier le flux à deux événements. Le premier webhook devrait avoir isFinalEvent: false. Le second (livraison à l'utilisateur) devrait avoir isFinalEvent: true.

Vérification des journaux d'activité du webhook

Zendesk conserve les journaux de webhook pendant 7 jours. Naviguez vers Centre d'administration > Applications et intégrations > Webhooks, sélectionnez votre webhook, et visualisez l'onglet Activité. Cela montre les livraisons récentes, les codes de réponse et toutes les erreurs.

Si vous ne voyez pas les webhooks attendus, vérifiez :

• Le webhook est-il actif (pas en pause) ?
• Les abonnements aux événements sont-ils corrects ?
• Votre endpoint répond-il avec des codes d'état 2xx ?

Dépannage des problèmes courants

Même avec une configuration soignée, les choses tournent mal. Voici les problèmes les plus courants et comment les résoudre.

Webhook ne se déclenchant pas

Si vous ne recevez pas de webhooks lorsque des messages sont envoyés :

• Vérifiez que le webhook est actif (pas en pause ou en état de brouillon)
• Vérifiez que les types d'événements corrects sont abonnés
• Pour les webhooks connectés à un déclencheur, vérifiez que les conditions du déclencheur sont remplies
• Vérifiez les journaux d'activité du webhook pour les schémas d'échec

Erreurs d'authentification (401/403)

Si Zendesk signale des échecs d'authentification :

• Vérifiez que votre endpoint vérifie le bon en-tête
• Confirmez que la clé API/le jeton n'a pas expiré
• Vérifiez la sensibilité à la casse dans les noms d'en-tête
• Si vous utilisez la vérification de signature, assurez-vous que vous calculez correctement le HMAC

Délais d'attente et disjoncteur

Zendesk a un délai d'attente de 10 secondes. Si votre endpoint prend plus de temps :

• Répondez immédiatement (200 OK) et traitez de manière asynchrone
• Utilisez une file d'attente de messages (SQS, RabbitMQ, etc.) pour le traitement lourd
• Surveillez les temps de traitement et optimisez les opérations lentes

Le disjoncteur se déclenche à un taux d'erreur de 70 % ou plus de 1 000 erreurs en 5 minutes. Si cela se produit, Zendesk met en pause votre webhook. Vous devrez corriger le problème sous-jacent et réactiver le webhook manuellement.

Événements de livraison manquants

Si vous voyez certains événements mais pas d'autres :

• Vérifiez la matrice de prise en charge des canaux. Tous les canaux n'envoient pas de confirmations de livraison à l'utilisateur.
• Pour WhatsApp spécifiquement, les événements de livraison à l'utilisateur peuvent être retardés ou supprimés si le message est reçu en dehors d'une certaine fenêtre de temps.
• Vérifiez le comportement de isFinalEvent. S'il est true au niveau du canal, aucun événement de livraison à l'utilisateur ne suivra.

Meilleures pratiques pour la production

Une fois que votre webhook fonctionne, considérez ces recommandations de production.

Gestion des erreurs et surveillance

• Enregistrez tous les reçus de webhook avec les ID d'événements pour le débogage
• Configurez des alertes pour les taux d'erreur élevés
• Surveillez les temps de réponse des endpoints
• Suivez les taux de livraison par canal pour repérer les problèmes tôt

Sécurité

• Utilisez toujours HTTPS en production
• Implémentez la vérification de signature du webhook
• Faites pivoter les clés API périodiquement
• N'enregistrez pas les données de payload sensibles

Conservation des données

Les événements de livraison contiennent des métadonnées de message. Considérez :

• Combien de temps conserver les journaux d'événements
• S'il faut stocker les payloads complets ou seulement les champs clés
• Les exigences de conformité (RGPD, etc.) pour les données de message

Quand interroger vs. utiliser des webhooks

Les webhooks sont idéaux pour les mises à jour en temps réel. Mais si vous avez besoin de données historiques ou d'événements manqués, vous pourriez avoir besoin de compléter avec l'interrogation. L'API List Messages peut combler les lacunes.

Rationalisez les flux de travail de messagerie avec eesel AI

La construction d'endpoints de webhook personnalisés prend du temps d'ingénierie. Vous devez gérer l'authentification, les nouvelles tentatives, l'idempotence et les cas d'erreur. Ensuite, vous devez construire la logique métier réelle par-dessus ces événements.

Nous avons construit eesel AI pour gérer cette complexité pour vous. Au lieu de gérer les webhooks vous-même, vous obtenez une automatisation de la messagerie clé en main avec le suivi de la livraison intégré. Notre coéquipier AI s'intègre à Zendesk (et Freshdesk, Gorgias, et autres) pour gérer les conversations de bout en bout.

Si vous recherchez un chemin plus rapide vers la messagerie alimentée par l'IA, consultez notre guide complet des webhooks de messagerie Zendesk. Et si vous voulez comparer les options, consultez notre analyse des meilleurs chatbots AI pour Zendesk.