# Webhooks

Webhooks are similar to periodic reminders/prompts from our server that respond to key events, actions and updates by notifying your server through the endpoint you provided in your API and Webhook URL page within your dashboard - A virtual mail man that delivers every single notifiable update(JSON-formatted data) to your server. 

Yeah, something like that, just that your house address (webhook url/endpoint) is all he needs to deliver the package while you (as expected) need to have the right pair of keys to decrypt the payload after identifying the signatures that verifies that it is from us.

## Technically

A webhook endpoint is a post endpoint on your server that accepts a HTTP `post` request from our server, Parses a JSON data and returns a `200 OK` response. 

If we do not receive a `200 OK` from your webhook, we will resend the data every 5 minutes for the first 3 attempts and in 20 minutes for the next 2 attempts.

 

{% hint style="info" %}
Kindly ensure that you apply standard coding practices while retrieving your payload data from us to avoid duplication of data or inconsistent registration of data within your server. Our server might send a successful data payload twice; ensure that you have a logic that processes the required webhook payload first on every request, and, as well, a logic that tracks against double referencing within your codebase.

Finally, test your webhook responses to confirm that you are receiving JSON data correctly from us before going live.
{% endhint %}

### Types of events

Here are the key events that we currently send to your webhook endpoint.

| Event Name              | Description                                                                |
| ----------------------- | -------------------------------------------------------------------------- |
| `transaction.success`   | A transaction has been successfully completed and you can deliver value    |
| `transaction.failed`    | The transaction has failed                                                 |
| `transaction.pending`   | A transaction has been initiated.                                          |
| `paymenttoken.paid`     | A transaction code has been successfully redeemed.                         |
| `paymenttoken.settled`  | We have automatically paid you for an unverified but expired token         |
| `paymenttoken.refunded` | We just invalidated a transaction and the money has been logged for refund |
| `transfer.success`      | A payout transfer has been confirmed successfully                          |
| `transfer.failed`       | A payout transfer failed                                                   |
| `transfer.pending`      | A payout transfer has been initialized and is pending verification         |

#### Sample WebHook Payload

<pre class="language-json" data-overflow="wrap" data-line-numbers data-full-width="false"><code class="lang-json">{
event: "transaction.success", 
<strong>status: true, 
</strong>message: "Transaction Retrieved Successfully",
data: {
    fee: 1947, 
    amount: 64890, 
    success: true, 
    currency: "NGN",
    event_id: 189368,
    reference: "jid1102832823",
    transaction_id: "jid1102832823-CUS_TsZkXu31tKs3-9037",
    customer: {
        name: "Sanmi David", 
        email: "sanmi@dmail.com", 
        phone: "081928392"}, 
        metadata: {
            location: "Abuja", 
            accessories: [{
                shoe: "NIke Airmax",
                color: "payload and benefits"
            }]}, 
    products: [{
            name: "Pencil Cooler", 
            amount: 63000, 
            description: "COlor blue"
        }], 
    ip_address: "127.0.0.1", 
    authorization: {
        bank: "Stanbic IBTC Bank",
        accountName: "Stephen Akinwale",
        accountNumber: "0987654321"
    },
<strong>    enc_payload: "yMBnea9eeDJwidXLJTVU78UvpkLmqNE7ufhoocxJR8yCpiq6+mjGf8MTEt4fW+WDcW/4ZugDDk5xMrqcKt+V+tHFO5SUea59ItMtD79NqnmIyY+s+XTh5ummY9Uww=="
</strong>    }
}
</code></pre>


---

# 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://developer.browpay.com/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.