> ## 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 payment 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

### checkout.completed

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

**Event Payload:**

```json theme={null}
{
  "event": "checkout.completed",
  "data": {
    "userId": "68fa3195501b6057c4d09f54",
    "reference": "DMBC20251110154056OSPHM",
    "merchantsReference": "DMBC20251110154056OSPHM",
    "status": "success",
    "amount": 200000,
    "customer": {
      "id": "69084137da4cde9706ab5c48",
      "phoneNumber": "2250538102473",
      "name": "Sample User"
    }
  }
}
```

**Field Descriptions:**

| Field                       | Type   | Description                                                             |
| --------------------------- | ------ | ----------------------------------------------------------------------- |
| `event`                     | String | The type of event. Will be "checkout.completed" for successful payments |
| `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                                                     |