Format de la charge utile des webhooks Zendesk : un guide complet pour les développeurs

Les webhooks transforment votre compte Zendesk en un moteur de notification en temps réel. Au lieu d'interroger les API pour obtenir des mises à jour, les webhooks envoient des données à vos systèmes dès que quelque chose se produit : un ticket est créé, un agent met à jour une priorité ou un client soumet des commentaires. Mais pour créer des intégrations fiables, vous devrez comprendre exactement quelles données Zendesk envoie et comment elles sont structurées.

Ce guide décompose le format de la charge utile des webhooks Zendesk de fond en comble. Vous découvrirez les deux types de webhooks proposés par Zendesk, la structure exacte des charges utiles d'événements, comment vérifier l'authenticité des webhooks et des conseils de mise en œuvre pratiques. Que vous créiez une intégration personnalisée ou que vous connectiez Zendesk à des outils tiers, il est essentiel de comprendre ces formats de charge utile.

Chez eesel AI, nous traitons les données des webhooks de Zendesk et d'autres plateformes pour alimenter l'automatisation intelligente. Obtenir le bon format de charge utile est la première étape vers la création d'intégrations robustes et sécurisées.

Les deux types de webhooks Zendesk

Zendesk propose deux méthodes de connexion de webhook fondamentalement différentes, et le choix que vous faites détermine vos options de format de charge utile. Vous ne pouvez pas modifier cette décision ultérieurement, il est donc utile de comprendre les deux approches à l'avance.

Webhooks abonnés aux événements

Ces webhooks s'abonnent directement aux événements système Zendesk. Lorsqu'un utilisateur est créé, qu'un état de ticket change ou qu'une organisation est mise à jour, Zendesk envoie automatiquement un webhook à votre point de terminaison.

Voici ce que vous devez savoir :

• Méthode HTTP : POST uniquement
• Format de requête : JSON uniquement
• Structure de la charge utile : Schéma fixe défini par Zendesk
• Idéal pour : Les notifications en temps réel concernant l'activité des utilisateurs, des organisations, du centre d'aide ou de la messagerie

La charge utile est prévisible. Zendesk contrôle les données envoyées, ce qui signifie moins de flexibilité, mais aussi moins de marge d'erreur de configuration.

Webhooks de déclencheurs et d'automatisation

Ceux-ci se connectent aux règles métier de Zendesk : déclencheurs et automatisations. Vous définissez exactement quand le webhook se déclenche en fonction des conditions du ticket.

Principales caractéristiques :

• Méthodes HTTP : GET, POST, PUT, PATCH, DELETE
• Format de requête : JSON, XML ou codé en formulaire
• Structure de la charge utile : Entièrement personnalisable à l'aide d'espaces réservés de balisage Liquid
• Idéal pour : Les flux de travail basés sur les tickets avec une logique conditionnelle

Cette approche vous donne un contrôle total sur la charge utile. Vous décidez quelles données inclure et comment les formater.

Choisir la bonne approche

Si vous devez réagir aux modifications de ticket avec une logique personnalisée, utilisez les webhooks de déclencheur. Pour les événements système plus larges tels que la création d'utilisateur ou l'activité de messagerie, les webhooks abonnés aux événements sont plus adaptés.

Anatomie d'une requête webhook

Chaque requête webhook de Zendesk inclut des en-têtes HTTP standard qui fournissent des métadonnées sur la requête. La compréhension de ces en-têtes est essentielle pour le routage, la journalisation et la vérification de la sécurité.

En-têtes standard

Les en-têtes de signature sont facultatifs, mais recommandés pour les intégrations de production. Ils vous permettent de vérifier que les requêtes proviennent réellement de Zendesk et aident à prévenir les attaques de relecture.

Différences de structure de requête

Les webhooks abonnés aux événements utilisent toujours POST avec des charges utiles JSON. Le corps contient les données complètes de l'événement dans un schéma standardisé.

Les webhooks de déclencheur varient en fonction de votre configuration. Une requête GET peut inclure des paramètres dans l'URL, tandis que les requêtes POST incluent un corps formaté en JSON, XML ou en données codées en formulaire en fonction de vos paramètres.

Structure et exemples de charge utile d'événement

Les webhooks abonnés aux événements utilisent un schéma JSON cohérent pour tous les types d'événements. Une fois que vous comprenez la structure, l'analyse de n'importe quel événement devient simple.

Schéma d'événement standard

Chaque charge utile d'événement inclut ces propriétés de niveau supérieur :

{
  "type": "zen:event-type:ticket.created",
  "account_id": 12514403,
  "id": "2b24ef10-19d4-4740-93cf-8f98ec4776c0",
  "time": "2099-07-04T05:33:18Z",
  "zendesk_event_version": "2022-06-20",
  "subject": "zen:ticket:12345",
  "detail": { /* resource details */ },
  "event": { /* change information */ }
}

Événement de ticket créé

Lorsqu'un nouveau ticket est créé, Zendesk envoie une charge utile comme celle-ci :

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

L'objet detail contient l'enregistrement complet du ticket. L'objet event pour les événements de création inclut uniquement des métadonnées sur la séquence d'événements.

Événement d'état modifié

Les événements de mise à jour incluent un objet event plus détaillé indiquant ce qui a changé :

{
  "event": {
    "current": "OPEN",
    "meta": {
      "sequence": {
        "id": 39313930383633353634323835,
        "position": 1
      }
    },
    "previous": "NEW"
  }
}

Les propriétés current et previous affichent les valeurs avant et après. Pour les changements d'état, les valeurs possibles incluent : NEW, OPEN, PENDING, HOLD, SOLVED, CLOSED, DELETED, ARCHIVED et SCRUBBED.

Événement de priorité modifiée

Les événements de priorité suivent le même modèle :

{
  "event": {
    "current": "URGENT",
    "meta": { "sequence": { "id": 39313930383633353634323835, "position": 1 } },
    "previous": "NORMAL"
  }
}

Les valeurs de priorité sont : LOW, NORMAL, HIGH et URGENT.

Événement de commentaire ajouté

Lorsque quelqu'un ajoute un commentaire à un ticket :

{
  "event": {
    "comment": {
      "author": {
        "id": "8659716080510",
        "is_staff": false,
        "name": "John Smith"
      },
      "body": "Thanks for the quick response!",
      "id": "8659716087550",
      "is_public": true
    },
    "meta": { "sequence": { "id": 39313930383633353634323835, "position": 1 } }
  }
}

L'objet commentaire inclut le texte complet, les informations sur l'auteur et l'état de visibilité.

Événement de balises modifiées

Pour les mises à jour de balises, Zendesk indique ce qui a été ajouté et supprimé :

{
  "event": {
    "meta": { "sequence": { "id": 39313930383633353634323835, "position": 1 } },
    "tags_added": ["urgent", "vip"],
    "tags_removed": ["pending-review"]
  }
}

Cette structure facilite le suivi des modifications de balises sans comparer les tableaux complets.

Charges utiles et espaces réservés des webhooks de déclencheur

Les webhooks de déclencheur et d'automatisation vous donnent un contrôle total sur le format de la charge utile à l'aide d'espaces réservés de balisage Liquid.

Espaces réservés courants

Exemple de charge utile JSON personnalisée

Vous pouvez créer des charges utiles personnalisées comme celle-ci :

{
  "event": "ticket_updated",
  "ticket_id": "{{ticket.id}}",
  "ticket_url": "{{ticket.url}}",
  "subject": "{{ticket.title}}",
  "description": "{{ticket.description}}",
  "status": "{{ticket.status}}",
  "priority": "{{ticket.priority}}",
  "requester": {
    "name": "{{ticket.requester.name}}",
    "email": "{{ticket.requester.email}}"
  },
  "assignee": {
    "name": "{{ticket.assignee.name}}",
    "email": "{{ticket.assignee.email}}"
  },
  "tags": "{{ticket.tags}}",
  "updated_by": "{{current_user.name}}"
}

Limites de taille de la charge utile

Les charges utiles personnalisées ont une taille maximale de 256 Ko. Si votre charge utile dépasse cette limite, Zendesk la tronque. Vous devrez surveiller les charges utiles qui incluent de grands champs de description ou de nombreux champs personnalisés.

Authentification et sécurité

La sécurisation de vos points de terminaison de webhook est essentielle. Zendesk fournit plusieurs options d'authentification pour vérifier les requêtes entrantes.

Vérification de la signature

La méthode la plus sécurisée utilise les signatures HMAC-SHA256. Zendesk génère une signature à partir de l'horodatage et du corps de la requête, que vous pouvez vérifier sur votre serveur.

Algorithme : base64(HMACSHA256(TIMESTAMP + BODY))

Exemple de vérification Node.js :

const crypto = require("crypto");

const SIGNING_SECRET = "your_webhook_signing_secret";
const SIGNING_SECRET_ALGORITHM = "sha256";

function isValidSignature(signature, body, timestamp) {
  let hmac = crypto.createHmac(SIGNING_SECRET_ALGORITHM, SIGNING_SECRET);
  let sig = hmac.update(timestamp + body).digest("base64");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(sig)
  );
}

Exemple de vérification Python :

import hmac
import hashlib
import base64

def verify_signature(payload, signature, timestamp, secret):
    message = timestamp + payload
    computed = base64.b64encode(
        hmac.new(
            secret.encode('utf-8'),
            message.encode('utf-8'),
            hashlib.sha256
        ).digest()
    ).decode('utf-8')
    return hmac.compare_digest(computed, signature)

Secrets de signature

Chaque webhook a un secret de signature unique. Vous pouvez le récupérer dans le Centre d'administration Zendesk en cliquant sur « Afficher le secret » sur la page des détails du webhook, ou via l'API à l'adresse GET /api/v2/webhooks/{id}/signing_secret.

Pour tester les webhooks avant la création, utilisez ce secret statique : dGhpc19zZWNyZXRfaXNfZm9yX3Rlc3Rpbmdfb25seQ==

Méthodes d'authentification supplémentaires

Au-delà de la vérification de la signature, Zendesk prend en charge :

• Authentification par clé API : Ajoutez un en-tête personnalisé avec votre clé API
• Authentification de base : Nom d'utilisateur et mot de passe ou jeton API
• Jeton de porteur : Authentification par jeton de type OAuth

Meilleures pratiques de sécurité

• Utilisez toujours des points de terminaison HTTPS
• Vérifiez les signatures dans les environnements de production
• Validez les horodatages pour éviter les attaques de relecture (rejetez les requêtes datant de plus de 5 minutes)
• Stockez les secrets dans des variables d'environnement, jamais dans le code
• Rendez vos gestionnaires de webhook idempotents (Zendesk peut réessayer ou envoyer des doublons)

Tests et dépannage

Avant de déployer des webhooks en production, vous aurez besoin de stratégies de test fiables.

Utilisation de webhook.site

Webhook.site fournit une URL temporaire gratuite qui capture les requêtes entrantes. Il est parfait pour inspecter les charges utiles de webhook brutes pendant le développement. Vous obtenez une URL unique qui affiche les en-têtes et le contenu du corps en temps réel.

Tests intégrés de Zendesk

Lors de la création ou de la modification d'un webhook dans le Centre d'administration, Zendesk fournit une fonctionnalité de test. Vous pouvez envoyer une charge utile de test à votre point de terminaison et voir la réponse. Cela permet de vérifier la connectivité et le format de la charge utile avant la mise en service.

Erreurs courantes et solutions

Comportement de nouvelle tentative

Zendesk relance automatiquement les webhooks ayant échoué :

• Erreurs HTTP 409 : jusqu'à 3 nouvelles tentatives
• HTTP 429/503 avec en-tête retry-after de moins de 60 secondes : relancé
• Délais d'attente (limite de 12 secondes) : jusqu'à 5 nouvelles tentatives

Le disjoncteur s'active lorsque 70 % des requêtes échouent en 5 minutes ou que plus de 1 000 erreurs se produisent. Il interrompt le webhook pendant 5 secondes, puis tente une requête. En cas de succès, le fonctionnement normal reprend.

Intégration des webhooks à eesel AI

Les webhooks deviennent plus puissants lorsqu'ils sont combinés à un traitement intelligent. Chez eesel AI, nous aidons les équipes à automatiser les flux de travail en traitant les données des webhooks de Zendesk et d'autres plateformes.

Voici comment l'intégration des webhooks améliore les opérations de support :

• Tri intelligent : Traitez les webhooks de création de ticket pour catégoriser et acheminer automatiquement les tickets en fonction de l'analyse du contenu
• Réponses automatisées : Déclenchez des réponses contextuelles à l'aide des données de webhook sur l'état du ticket et les changements de priorité
• Enrichissement des données : Combinez les charges utiles de webhook avec des sources de données internes pour fournir aux agents un contexte client complet
• Synchronisation multiplateforme : Utilisez les webhooks pour maintenir Zendesk synchronisé avec le CRM, l'inventaire ou d'autres systèmes d'entreprise

Notre intégration Zendesk se connecte directement à votre compte, apprenant de vos anciens tickets et de votre centre d'aide pour fournir une automatisation intelligente. Les webhooks étendent cette capacité en permettant des déclencheurs et des actions en temps réel.

Principaux points à retenir et meilleures pratiques

La création d'intégrations de webhook fiables nécessite une attention particulière aux détails. Voici ce que vous voudrez retenir :

Choisissez le bon type de webhook : Les webhooks abonnés aux événements fonctionnent mieux pour les notifications à l'échelle du système, tandis que les webhooks de déclencheur vous offrent une flexibilité pour les flux de travail spécifiques aux tickets.

Vérifiez les signatures en production : La vérification de la signature HMAC-SHA256 garantit que les requêtes proviennent de Zendesk et n'ont pas été falsifiées.

Gérez les nouvelles tentatives avec élégance : Zendesk peut relancer les requêtes ayant échoué ou envoyer des doublons. Concevez vos gestionnaires pour qu'ils soient idempotents.

Surveillez l'état du webhook : Utilisez le journal d'activité et l'état du disjoncteur pour détecter les problèmes rapidement.

Testez minutieusement : Utilisez des outils comme webhook.site pour inspecter les charges utiles avant de les déployer en production.

La compréhension du format de la charge utile des webhooks Zendesk est la base de la création d'intégrations robustes. Avec la bonne approche de la sécurité, des tests et de la gestion des erreurs, vous pouvez créer des connexions fiables qui maintiennent vos systèmes synchronisés et votre équipe informée.