> ## Documentation Index
> Fetch the complete documentation index at: https://docs.delivery-api.express.ci/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Overview of how our Webhook works

A webhook is a callback function based on the HTTP protocol.

It allows a remote API to establish event-oriented communication with our API.

* In our system, an event corresponds to a change in the order status. When an event occurs, our system notifies you by calling the URL you provided.

## How Our Webhook Works

1. **Subscription to Events**: The remote API (client) subscribes to events on our API by providing a callback URL where events will be sent.
2. **Event Triggering**: When an event occurs within our system, a `POST` request is sent to the client's callback URL with details about the event.
3. **Payload**: The payload of the `POST` request contains information about the status of the order.
4. **Response Handling**: The client’s server processes the incoming webhook payload and responds with a status code to acknowledge receipt.

## Steps to Set Up a Webhook

<Steps>
  <Step title="Register a Webhook">
    Provide the callback URL where events will be sent. [Create
    Webhook](/api-reference/webhook/endpoint/create-webhook)
  </Step>

  <Step title="Handle Incoming Requests">
    Ensure your server can handle POST requests and process the incoming event
    data.
  </Step>

  <Step title="Acknowledge Receipt">
    Respond to the webhook POST request with a 2xx status code to acknowledge
    successful receipt.
  </Step>
</Steps>

## Example Webhook Payload

```json theme={null}
{
  "referenceNumber": "ORD1749113582",
  "total": 98150,
  "deliveryFee": 1500,
  "deliveryInstructions": "Livrer dans l'après midi",
  "deliveryDeadline": "2025-06-05",
  "deliveryPartnerId": null,
  "status": "completed",
  "statusComment": null,
  "createdAt": "2025-06-05T08:51:04.000Z",
  "updatedAt": "2025-06-05T08:51:04.000Z",
  "recipient": {
    "referenceNumber": null,
    "name": "John Doe",
    "phone": "0702029254",
    "address": {
      "name": "45 Avenue de la Paix",
      "landmark": "Terminus 81/82",
      "city": "Cocody",
      "latitude": 5.403871,
      "longitude": -3.988108
    }
  },
  "items": [
    {
      "referenceNumber": "ITEM1749114011",
      "itemName": "Samsung Galaxy A05 64Go",
      "quantity": 1,
      "total": 77900,
      "size": "S",
      "weight": 0.5,
      "itemUrl": "https://market.momo.africa/Portal/product/121731/1?tenantId=4&lang=fr",
      "status": "delivered",
      "statusComment": null,
      "createdAt": "2025-06-05T08:51:04.000Z",
      "updatedAt": "2025-06-05T08:51:04.000Z",
      "sender": {
        "referenceNumber": "0596086680",
        "name": "MTN Market Store",
        "phone": "0700000001",
        "address": {
          "name": "8X9P+38P, Rue du Commerce, Abidjan, Côte d'Ivoire",
          "landmark": "Address landmark",
          "city": "Cocody",
          "latitude": 5.39909,
          "longitude": -3.999493
        }
      }
    },
    {
      "referenceNumber": "ITEM1749113806",
      "orderId": 15,
      "itemName": "Riz vietnamien La Rizière long grains parfumé 5kg",
      "quantity": 5,
      "total": 18750,
      "size": "S",
      "weight": 5.5,
      "itemUrl": "https://market.momo.africa/Portal/product/107465/1?tenantId=4&lang=fr",
      "status": "delivered",
      "statusComment": null,
      "createdAt": "2025-06-05T08:51:04.000Z",
      "updatedAt": "2025-06-05T08:51:04.000Z",
      "sender": {
        "referenceNumber": "0555306590",
        "name": "Tech Shop",
        "phone": "0700000002",
        "address": {
          "name": "456 Avenue Tech",
          "landmark": "Liberté",
          "city": "Adjamé",
          "latitude": 5.353307,
          "longitude": -4.017547
        }
      }
    }
  ]
}
```