> For the complete documentation index, see [llms.txt](https://apidocs.paygateway.paytota.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.paygateway.paytota.com/webhook.md).

# Webhook

1. All `collection` and `disbursement` transactions notification updates will be sent as **`POST`** to the URL set as the `webhook url` under your merchant account API tokens.<br>
2. Only, `https` URLs can be set or notified.<br>
3. You will need to acknowledge receipt of the notification by responding with the HTTP status code **`200`**. Otherwise, we might keep calling your webhook URL at an interval of 10 minutes for 2 days.<br>
4. To ensure that the notification data sent to your `webhook URL` comes from our servers, set a `webhook hash` under the `Api Tokens`.<br>
5. We will include a header called, `webhook-hash` in the request sent to the `webhook URL`. e.g **webhook-hash: WH-\*\*\*"**

{% hint style="info" %}
You should verify the `webhook-hash` we sent matches what was set under your merchant account before giving service to your customer
{% endhint %}

#### **Responding to webhooks**

We will stop sending notification to your webhook URL if it responds with the following “HTTP status codes” below;

| Code  | Description             |
| ----- | ----------------------- |
| `200` | - OK                    |
| `400` | - Bad Request           |
| `401` | - Unauthorised          |
| `403` | - Forbidden             |
| `422` | - Unprocessable entity. |

**Rejecting webhook notification**

In a scenario where the transaction cannot be processed respond with HTTP codes below;

| Code  | Description                                                                                                                                      |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400` | <p>- Bad Request.<br>- e.g when there’s a missing parameter</p>                                                                                  |
| `422` | <p>- Unprocessable entity.<br>- e.g when the request is fine but you cannot complete it because the amount does not match what you expected.</p> |

{% hint style="danger" %}
**KEYNOTE**

Always verify the, **`amount`** to make sure it matches what is meant to be **`paid`** before giving service to the customer.
{% endhint %}

```javascript
{
    "id": "383737927636356536773773",
    "request_amount": 0.4,
    "request_currency": "USD",
    "account_amount": 1462.53,
    "account_currency": "UGX",
    "transaction_fee": 42.23,
    "total_credit": 1420.30,
    "customer_charged": false,
    "provider": "mtn_ug",
    "merchant_reference": "88736jh-kkas87-mmn736-9n873ms-6636h",
    "paytota_reference": "PL-KMSSD-30000",
    "transaction_status": "COMPLETED",
    "transaction_type": "collection",
    "message": "Transaction Completed Successfully",
    "account_number": "Optional - 256777111222",
    "account_name": "Optional",
    "institution_name": "Optional - MTN Mobile Money Uganda"
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://apidocs.paygateway.paytota.com/webhook.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.