Démarrage rapide des webhooks

Les webhooks informent vos propres systèmes à l’instant où quelque chose se passe dans Zippendo, par exemple lorsqu’une expédition est envoyée ou qu’un statut de suivi change, pour que votre boutique en ligne ou votre ERP reste à jour sans interroger l’API sans cesse.

Les webhooks sont inclus dans toutes les formules.

1. Ajouter un webhook

Ouvrez Webhooks

Dans app.zippendo.com, ouvrez le menu de l’organisation en bas de la barre latérale, cliquez sur Gérer, puis sur Webhooks.

Créez le webhook

Cliquez sur Ajouter un webhook. Saisissez un Nom et votre URL de destination, cochez les Événements souhaités, puis cliquez sur Créer un webhook.

Récupérez le secret de signature

Zippendo crée un secret de signature pour chaque webhook. L’application ne l’affiche pas : lisez-le avec l’API depuis GET /orgs/{orgId}/webhooks/{webhookId}, ou depuis la réponse lorsque vous créez le webhook via l’API avec POST /orgs/{orgId}/webhooks. Conservez-le sur votre serveur et vérifiez la signature à chaque envoi.

2. Événements

Événement	Envoyé lorsque
`shipment.created`	Une expédition est créée
`shipment.updated`	Une expédition est modifiée
`shipment.dispatched`	Une expédition est envoyée au transporteur
`shipment.cancelled`	Une expédition est supprimée
`shipment.error`	L’envoi d’une expédition au transporteur échoue
`order.created`	Une commande est créée dans l’application ou via l’API
`order.updated`	Une commande est modifiée dans l’application ou via l’API
`order.cancelled`	Une commande est supprimée dans l’application ou via l’API
`tracking.updated`	Un colis reçoit un nouvel événement de suivi

Les commandes importées depuis un canal de vente n’envoient pas d’événements order.*. Envoyer un test sur un webhook envoie un événement webhook.test à ce seul point de terminaison.

3. Le contrat d’envoi

Chaque envoi est un POST HTTPS avec un corps JSON de la forme { "event", "timestamp", "brandId", "data" } et trois en-têtes :

En-tête	Valeur
`X-Webhook-Signature`	HMAC-SHA256 du corps brut de la requête, encodé en hexadécimal, avec le secret de signature du webhook comme clé
`X-Webhook-Event`	Le nom de l’événement, par exemple `shipment.dispatched`
`X-Webhook-Id`	ID d’envoi unique. Un envoi réessayé conserve le même ID.

Un envoi expire au bout de 10 secondes. Toute réponse autre que 2xx, ou une expiration, est comptée comme un échec, et Zippendo réessaie avec une pause de plus en plus longue entre les tentatives : jusqu’à 5 tentatives au total. Chaque tentative, réussie ou non, figure dans le Journal des envois du webhook sous Webhooks.

4. Traiter les envois

Votre point de terminaison doit :

Répondre rapidement avec un statut 2xx, et effectuer les traitements lourds en arrière-plan
Utiliser HTTPS
Vérifier la signature avant de se fier au corps
Gérer les nouvelles tentatives en toute sécurité : utilisez X-Webhook-Id pour ignorer un envoi déjà traité

import crypto from "node:crypto"

export async function POST(request) {
  const body = await request.text()

  const expected = crypto.createHmac("sha256", process.env.ZIPPENDO_WEBHOOK_SECRET)
    .update(body)
    .digest("hex")
  const signature = request.headers.get("x-webhook-signature") ?? ""
  const valid = signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
  if (!valid) return new Response("invalid signature", { status: 401 })

  queueMicrotask(() => processZippendoEvent(JSON.parse(body)))
  return new Response("ok", { status: 200 })
}

5. Tester pendant le développement

Utilisez un tunnel (par exemple ngrok) pour donner à votre serveur de développement une adresse HTTPS publique, comme https://your-tunnel.ngrok.io/webhooks/zippendo. Faites pointer un webhook de test vers cette adresse et cliquez sur Envoyer un test.

Étapes suivantes

Guide des webhooks

Modifiez, suspendez et supprimez des webhooks, et consultez le journal des envois.

API REST

Combinez les webhooks avec des appels d’API lorsque vous avez besoin de données à la demande.

Démarrer

Démarrages rapides

Flux d'expédition

Connexions

Opérations

Organisation et compte

Démarrage rapide des webhooks

1. Ajouter un webhook

2. Événements

3. Le contrat d’envoi

4. Traiter les envois

5. Tester pendant le développement

Étapes suivantes

Guide des webhooks

API REST

​1. Ajouter un webhook

​2. Événements

​3. Le contrat d’envoi

​4. Traiter les envois

​5. Tester pendant le développement

​Étapes suivantes

Guide des webhooks

API REST

1. Ajouter un webhook

2. Événements

3. Le contrat d’envoi

4. Traiter les envois

5. Tester pendant le développement

Étapes suivantes