Aller au contenu principal

Event catalog

Every webhook payload is wrapped:

{
  "event":       "<event name>",
  "store_id":    13,
  "occurred_at": "2026-04-30T21:18:21+00:00",
  "data":        { /* event-specific, documented below */ },
  "delivery_id": "abc123def456"
}

This page documents the data field for each event.

Order events​

The order goes through up to 7 status transitions in its lifetime. We fire one event per transition, not per state — so you get notified each time an order moves.

order.created​

Fires when a new order row lands (storefront checkout, API order, manual admin create).

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

order.confirmed​

Fires when status moves to confirmed. Stock is decremented at this 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​

Fires from any non-terminal state. If the order was already in a committed-stock state, stock is restored before this event fires.

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

order.returned​

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

Payment events​

payment.received​

Fires when a payment lands (SlickPay webhook, manual receipt approved). Independent of order.confirmed.

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

Signup / event tracking​

signup.counted​

Fires when a /v1/signups call lands and was actually counted (not a duplicate).

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

For privacy reasons we do NOT echo back email, phone, or external_user_id in the webhook — your own systems already have those values. The webhook is the "this signup was counted, please mirror it to your CRM" signal.

event.recorded​

Fires when a /v1/events call is recorded (currently optional; will become opt-in in v1.1 to reduce delivery volume).

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

Product events​

product.stock_low​

Fires when track_stock=true AND stock_quantity <= low_stock_alert. Once-per-threshold-crossing — we don't spam.

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

Internal / test​

webhook.test​

Fired by POST /v1/webhooks/{id}/test. Lets you verify signature handling without waiting for a real event.

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

Headers (every 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 per attempt>

Versioning​

We add new events under v1 freely (additive). When we change the shape of an existing event's data, that's a v2-required change and gets a new path prefix. So your code can rely on:

  • event is stable.
  • New top-level fields may appear in data.
  • Existing field types and meanings won't change without a v2.
  • Order of data keys is not guaranteed.