DOCS
AccueilPour les prestataires logistiques Webhooks

Écouter les événements avec les webhooks

Recevez des notifications d'événements en temps réel pour votre intégration Zonos.

Les webhooks permettent à Zonos de notifier proactivement vos systèmes externes lorsque certains événements se produisent. Lorsque l'événement souscrit se produit, Zonos envoie une requête HTTP POST à l'URL webhook que vous spécifiez. Le corps de la requête contiendra les détails de l'événement, permettant à votre système de le traiter par programmation.

Les webhooks sont utiles pour intégrer Zonos avec d'autres plateformes, déclencher des flux de travail automatisés et maintenir la synchronisation des données entre systèmes en temps réel. Par exemple, vous pourriez utiliser les webhooks pour :

  • Mettre à jour votre système de gestion des commandes lorsqu'une commande est créée dans Zonos
  • Notifier votre prestataire de fulfillment lorsqu'un envoi est annulé
  • Enregistrer les changements de statut des commandes internationales à des fins d'audit

Types de webhooks 

Tous les types de webhooks disponibles sont inclus dans l'énumération WebhookType. Des exemples de payload pour chacun se trouvent dans notre guide Types d'événements.

Créer des webhooks 

Pour créer un webhook via l'API :

1mutation WebhookCreate($input: WebhookCreateInput!) {
2 webhookCreate(input: $input) {
3 id
4 url
5 type
6 status
7 secret
8 headers {
9 key
10 }
11 }
12}

Important : Enregistrez la valeur du secret lors de la création du webhook — elle n'est retournée qu'à ce moment-là, et vous en aurez besoin pour vérifier les signatures des webhooks. Consultez Vérifier les signatures des webhooks ci-dessous.

Modifier les détails d'un webhook 

Pour modifier un webhook existant via l'API :

1mutation WebhookUpdate($input: WebhookUpdateInput!) {
2 webhookUpdate(input: $input) {
3 id
4 url
5 type
6 status
7 }
8}

Vérifier les signatures des webhooks 

Chaque requête webhook envoyée par Zonos inclut un en-tête zonos-signature qui vous permet de confirmer que la requête provient bien de Zonos et que la charge utile n'a pas été altérée pendant le transit.

La valeur de l'en-tête a le format suivant :

timestamp=<unix-timestamp-ms>,hmac=<base64-encoded-signature>
  • timestamp — l'heure, en millisecondes depuis l'epoch Unix, à laquelle la requête a été signée.
  • hmac — une signature HMAC-SHA256 du corps brut de la requête JSON, calculée à l'aide du secret de votre webhook comme clé et encodée en Base64.

Pour vérifier une requête :

  1. Extrayez les valeurs timestamp et hmac de l'en-tête zonos-signature.
  2. Calculez votre propre signature HMAC-SHA256 sur le corps brut, non analysé, de la requête, à l'aide du secret que vous avez reçu lors de la création du webhook.
  3. Comparez votre signature calculée à la valeur hmac à l'aide d'une comparaison en temps constant, et rejetez la requête si elles ne correspondent pas.
  4. Vous pouvez éventuellement rejeter les requêtes dont le timestamp date de plus de quelques minutes, afin de vous protéger contre la relecture (replay) d'une requête interceptée. Zonos n'impose pas lui-même de fenêtre de livraison ; cette vérification vous incombe donc.
1const crypto = require("crypto");
2 
3function verifyZonosWebhook(rawBody, signatureHeader, secret) {
4 const [timestampPart, hmacPart] = signatureHeader.split(",");
5 const receivedHmac = hmacPart.split("=")[1];
6 
7 const expectedHmac = crypto
8 .createHmac("sha256", secret)
9 .update(rawBody)
10 .digest("base64");
11 
12 const receivedBuffer = Buffer.from(receivedHmac);
13 const expectedBuffer = Buffer.from(expectedHmac);
14 
15 if (receivedBuffer.length !== expectedBuffer.length) {
16 return false;
17 }
18 
19 return crypto.timingSafeEqual(receivedBuffer, expectedBuffer);
20}

Remarque : Si vous avez configuré des en-têtes personnalisés sur votre webhook, ceux-ci sont également inclus tels quels dans chaque requête, en plus de zonos-signature.

Consulter les journaux de webhooks 

Pour consulter les journaux de webhooks via l'API :

1query WebhookLogs(
2$first: Int
3$after: String
4$filter: WebhookLogsFilterInput
5) {
6 webhookLogs(first: $first, after: $after, filter: $filter) {
7 edges {
8 node {
9 id
10 type
11 url
12 createdAt
13 responseStatus
14 }
15 }
16 }
17}
GraphQL API ReferenceTypes, inputs, and operations used in this guide
INPUTS

WebhookCreateInput WebhookLogsFilterInput WebhookUpdateInput

MUTATIONS

webhookCreate webhookUpdate

Cette page a-t-elle été utile?

Obtenir de l'aide·Documents juridiques·© 2026 Zonos
Sur cette page :
  • Écouter les événements avec les webhooks
  • Types de webhooks
  • Créer des webhooks
  • Modifier les détails d'un webhook
  • Vérifier les signatures des webhooks
  • Consulter les journaux de webhooks