# Webhooks

A webhook notifies you about a change in the status of an account on your platform. These notifications are delivered to your defined webhook/callback url provided and updated through your dashboard or API endpoint.

You may use these notifications to perform additional tasks on your application as it suits your business goals. The Webhook notifications are used to provide information on transactions happening on your internal accounts.

PIS webhooks are HTTP calls triggered by specific events. The webhooks replace regular API calls with instant, real-time notifications. It can be set up on your dashboard by specifying a URL we would send POST requests to you whenever an event is of interest.

To process notifications, you need to:

#### **Expose an endpoint on an open server**

We can send notifications as HTTP callbacks (webhooks) to an endpoint on a server that must be open. To receive webhooks, you must have a server that:

* Has an endpoint that can receive JSON requests
* Depending on your network and security requirements, you might also need to add our IP address to your firewall's whitelist.

#### **Accept the notifications**

To ensure that your server properly accepts notifications, we require you to acknowledge every notification with an HTTP 200 response code. When your server receives a notification:

1. Save the notification in your database.
2. Acknowledge the notification with the following HTTP response status code `200`.
3. Apply your business logic.

Make sure that you acknowledge the notification before applying any business logic, because a breakage in your business logic could otherwise prevent important updates from reaching your system.

Sample Webhook Event Format

```json
{
    "reference": "862405167800153080816502",
    "amount": 1000,
    "charge": "50",
    "settlement": 950,
    "account": {
        "reference": "19b0d2ca2983995133d622d52eba1e3f",
        "accountNumber": "2051857075",
        "accountName": "PIS - WALE BABATUNDE",
        "bank": "Kuda Microfinance Bank"
    },
    "payer": {
        "name": "MICHAEL OLANREWAJU SOMOYE",
        "bank": "Paycom(OPay)"
    },
    "secretHash": "3d68109c24f84f3d32c73f34319d0988710654832dcebc59205b77cc7743c5d7"
}
```


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pis.ng/v1.0/collections/virtual-bank-account/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.