> ## Documentation Index
> Fetch the complete documentation index at: https://www.zippendo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Démarrage rapide des webhooks

> Recevez sur votre serveur, en temps réel, les événements de Zippendo lorsque des expéditions, des commandes et le suivi changent.

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.

<Note>
  Les webhooks sont inclus dans toutes les formules.
</Note>

## 1. Ajouter un webhook

<Steps>
  <Step title="Ouvrez Webhooks">
    Dans [app.zippendo.com](https://app.zippendo.com), ouvrez le menu de l'organisation en bas de la barre latérale, cliquez sur **Gérer**, puis sur **Webhooks**.
  </Step>

  <Step title="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**.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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é

```javascript theme={null}
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

<CardGroup cols={2}>
  <Card title="Guide des webhooks" icon="book-open" href="/docs/fr/settings/webhooks">
    Modifiez, suspendez et supprimez des webhooks, et consultez le journal des envois.
  </Card>

  <Card title="API REST" icon="terminal" href="/docs/fr/quickstarts/rest-api">
    Combinez les webhooks avec des appels d'API lorsque vous avez besoin de données à la demande.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.