Aller au contenu principal

Catalogue d'événements

Chaque payload webhook est wrappé :

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

Cette page documente le champ data pour chaque event.

Événements de commande​

Une commande passe par jusqu'à 7 transitions de statut dans sa vie. On déclenche un event par transition, pas par état — vous êtes notifié à chaque mouvement.

order.created​

Déclenché à la création d'une commande (checkout vitrine, commande API, création admin manuelle).

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

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" } }

order.delivered​

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

order.cancelled​

Déclenché depuis tout état non-terminal. Si la commande était en stock engagé, le stock est restitué avant le déclenchement.

{ "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​

Déclenché à l'arrivée d'un paiement (webhook SlickPay, reçu manuel approuvé). Indépendant de order.confirmed.

{
  "data": {
    "order_id":  6894,
    "amount":    1000,
    "method":    "slickpay",
    "reference": "TRX-…"
  }
}

Tracking inscriptions / events​

signup.counted​

Déclenché quand un appel /v1/signups arrive et est effectivement compté (pas un doublon).

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

Pour confidentialité on ne renvoie PAS email, phone ni external_user_id dans le webhook — vos systèmes ont déjà ces valeurs. Le webhook est le signal « cette inscription a été comptée, miroitez-la dans votre CRM ».

event.recorded​

Déclenché à l'enregistrement d'un appel /v1/events (optionnel actuellement ; deviendra opt-in en v1.1 pour réduire le volume).

{
  "data": {
    "name":       "lead_submitted",
    "properties": { "form": "footer", "campaign": "spring-2026" }
  }
}

Événements produit​

product.stock_low​

Déclenché quand track_stock=true ET stock_quantity <= low_stock_alert. Une fois par franchissement de seuil — on ne spamme pas.

{
  "data": {
    "product_id":     26,
    "name":           "T-shirt - Cotton 200gsm",
    "stock_quantity": 4,
    "low_stock_alert": 5
  }
}

Interne / test​

webhook.test​

Déclenché par POST /v1/webhooks/{id}/test. Permet de vérifier la signature sans attendre un vrai event.

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

En-têtes (chaque event)​

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

Versioning​

On ajoute librement de nouveaux events sous v1 (additif). Quand on change la forme du data d'un event existant, c'est un changement v2 et reçoit un nouveau préfixe de chemin. Donc votre code peut compter sur :

  • event est stable.
  • De nouveaux champs top-level peuvent apparaître dans data.
  • Les types et significations existants ne changent pas sans v2.
  • L'ordre des clés data n'est pas garanti.