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

# Webhook

Webhooks allow you to receive real-time notifications when events occur on your Mobipurse merchant account. This is the most reliable way to track payment status and other important events.

## How Webhooks Work

When a significant event occurs (such as a disbursement completion), Mobipurse sends an HTTP POST request to the webhook URL you've configured. Your server should acknowledge receipt by responding with a `200 OK` status code.

## Setting Up Webhooks

You can configure your webhook URL in two ways:

1. **Per-checkout basis**: Include the `webhookURL` parameter when creating a checkout
2. **Global webhook**: Set a default webhook URL in your dashboard under **Settings → Webhooks**

### Webhook Priority

If a webhook URL is specified in the checkout creation request, it will be used. Otherwise, the global webhook URL from your dashboard settings will be used.

## Webhook Events

### disbursement.completed

This event is triggered when a customer successfully completes a payment.

**Event Payload:**

```json theme={null}
{
  "event": "disbursement.completed",
  "data": {
    "userId": "68fa3195501b6057c4d09f54",
    "reference": "DMBD20251110155014KVAZR",
    "merchantsReference": "5f86ad3c-2d4a-401e-959c-3e0db463b175",
    "status": "success",
    "amount": 10000,
    "customer": {
      "id": "68e47c6d8169d0c6e42e0638",
      "name": "Cordell Deckow",
      "phoneNumber": "2257038102473"
    }
  }
}
```

**Field Descriptions:**

| Field                       | Type   | Description                                                                      |
| --------------------------- | ------ | -------------------------------------------------------------------------------- |
| `event`                     | String | The type of event. Will be "disbursement.completed" for successful disbursements |
| `data.userId`               | String | The Mobipurse user ID of the merchant                                            |
| `data.reference`            | String | The unique reference generated by Mobipurse for this transaction                 |
| `data.merchantsReference`   | String | Your merchant reference for this transaction                                     |
| `data.status`               | String | The status of the payment. Can be "success", "failed", or "pending"              |
| `data.amount`               | Number | The amount of the transaction in the lowest currency denomination                |
| `data.customer.id`          | String | The unique ID of the customer who made the payment                               |
| `data.customer.phoneNumber` | String | The customer's phone number                                                      |
| `data.customer.name`        | String | The customer's name                                                              |