Chaque payload webhook est enveloppée :

{
  "event":       "<event name>",
  "store_id":    13,
  "occurred_at": "2026-04-30T21:18:21+00:00",
  "data":        { /* propre à l'événement, documenté ci-dessous */ },
  "delivery_id": "9f2c41ab77e05d18"
}

Cette page documente le champ data de chaque événement.

Événements de commande

⚠️ Attention — Les événements de commande API v1 ne suivent que le trafic API

Un événement de statut de commande se déclenche uniquement quand le statut est modifié via l'API — PATCH /v1/orders/{id} ou POST /v1/orders/{id}/cancel. Confirmer ou expédier depuis le dashboard DZBuild, l'envoi groupé en livraison et les mises à jour automatiques du suivi transporteur ne déclenchent rien ici.

Il y a par ailleurs 7 statuts de commande mais seulement 5 événements de statut : les transitions vers pending et vers processing n'émettent absolument rien. Une commande peut donc passer pending → processing → shipped et vous ne verrez qu'un seul order.shipped.

S'il vous faut des événements couvrant toutes les sources de commandes et tous les changements de statut, utilisez plutôt l'addon Webhooks marchand sur /dashboard/webhooks — voir la comparaison dans la Vue d'ensemble des Webhooks.

order.created

Déclenché uniquement pour les commandes créées via POST /v1/orders. Les commandes passées sur la boutique, sur une landing page ou créées manuellement au dashboard ne déclenchent pas cet événement — si vous y branchez votre logistique, vous manquerez l'écrasante majorité des commandes du marchand.

{
  "data": {
    "order_id":       6894,
    "order_number":   "ORD-13-20260317-AD3C",
    "customer_phone": "0555000000",
    "total":          1000
  }
}

Ces quatre clés constituent toute la payload. Appelez GET /v1/orders/{id} s'il vous faut autre chose.

order.confirmed

Déclenché à la transition vers confirmed. Le stock est décrémenté à ce moment.

{
  "data": {
    "order_id":   6894,
    "old_status": "pending",
    "new_status": "confirmed"
  }
}

order.shipped

{ "data": { "order_id": 6894, "old_status": "processing", "new_status": "shipped" } }

old_status peut être un état dont on ne vous a jamais parlé — dans cet exemple, le passage à processing n'a déclenché aucun événement propre.

order.delivered

{ "data": { "order_id": 6894, "old_status": "shipped", "new_status": "delivered" } }

order.cancelled

Déclenché quand une commande passe à cancelled depuis pending, confirmed ou processing — ce sont les seuls états depuis lesquels l'annulation est autorisée. POST /v1/orders/{id}/cancel sur une commande shipped ou delivered renvoie 400 bad_request et ne déclenche aucun événement. Si la commande était déjà dans un état à stock engagé, le stock est restitué avant que cet événement parte.

{ "data": { "order_id": 6894, "old_status": "confirmed", "new_status": "cancelled" } }

order.returned

{ "data": { "order_id": 6894, "old_status": "delivered", "new_status": "returned" } }

Événements de paiement

payment.received

Réservé — non émis actuellement. Le nom est accepté dans le tableau events à l'enregistrement et apparaît dans allowed_events, mais rien ne le déclenche. Les changements de statut de paiement n'arriveront pas sur votre endpoint ; lisez GET /v1/orders/{id} si vous en avez besoin.

Suivi des signups / événements

signup.counted

Déclenché quand un appel /v1/signups arrive et a réellement été compté (pas un doublon).

{
  "data": {
    "key_id":  "dzpub_live_53f32d45fc356",
    "source":  "landing-page-1",
    "country": "DZ"
  }
}

Pour des raisons de confidentialité, nous ne renvoyons PAS email, phone ni external_user_id dans le webhook — vos propres systèmes ont déjà ces valeurs. Le webhook est le signal « ce signup a été compté, répercutez-le dans votre CRM ».

event.recorded

Réservé — non émis actuellement. POST /v1/events enregistre l'événement et incrémente la consommation, mais ne déclenche aucun webhook.

Événements produit

product.stock_low

Réservé — non émis actuellement. Il n'existe aucun push de stock bas aujourd'hui.

Le champ sous-jacent est bien réel, en revanche : GET /v1/products/{id} renvoie low_stock_alert à côté de stock_quantity sous inventory, vous pouvez donc surveiller la condition vous-même par polling.

Interne / test

webhook.test

Déclenché par POST /v1/webhooks/{id}/test. Vous permet de vérifier que votre endpoint est joignable sans attendre un vrai événement.

{ "data": { "ts": 1717112657 } }

Il ne peut pas faire l'objet d'un abonnement — inclure webhook.test dans le tableau events à l'enregistrement renvoie 400 bad_request "unknown event: webhook.test. Allowed: …". Un test est livré au webhook sur lequel vous l'appelez, indépendamment de sa liste d'abonnements.

En-têtes (chaque événement)

Content-Type:    application/json
User-Agent:      dzbuild-webhook/1
X-DZ-Timestamp:  <unix seconds>
X-DZ-Signature:  <hex hmac-sha256>
X-DZ-Delivery-Id: <numeric delivery id>

X-DZ-Delivery-Id est un id numérique de livraison (par ex. 4127). Il est stable à chaque retry de cette livraison, et il n'est pas la même valeur que le delivery_id de 16 caractères hex présent dans le body JSON.

Versioning

Nous ajoutons librement de nouveaux events en v1 (additif). Quand nous changeons la forme du data d'un event existant, c'est un changement qui exige une v2 et un nouveau préfixe de chemin. Votre code peut donc compter sur :

event est stable.
De nouveaux champs de premier niveau peuvent apparaître dans data.
Les types et significations existants ne changeront pas sans v2.
L'ordre des clés de data n'est pas garanti.

Catalogue d'événements