# Webhook

We can notify a [registered pay widget merchant](/v1/integration-guide.md) about the statuses of orders associated with him.

We will make a **POST** request to a provided webhook URL with the next **application/json** contents:

**Webhook V1:**[**​**](https://docs.fonbnk.com/docs/pay-widget/webhook#webhook-v1)

{% code overflow="wrap" %}

```typescript
type WebhookRequest = {
  "data": {
    "status":
      | "swap_initiated" // user has created an order
      | "swap_expired" // an order has expired
      | "swap_buyer_rejected"  // user has rejected an order
      | "swap_buyer_confirmed" // user has confirmed an order
      | "swap_seller_rejected" // agent has rejected an order, happens when agent don't receive a payment
      | "swap_seller_confirmed" // agent has confirmed an order
      | "pending" // USDC/cUSD transaction is pending
      | "complete" // USDC/cUSD transaction is complete
      | "failed", // USDC/cUSD transaction has failed
    "date": string, // date when event has happened
    "orderId": string, // order id in our system
    "email": string, // customer's email
    "localCurrencyAmount": number, // amount of local currency user paid
    "localCurrencyIsoCode": string, // ISO code of local currency user paid, e.g. KES, NGN etc.
    "countryIsoCode": string, // ISO code of country user paid from, e.g. KE, NG etc.
    "provider": // payment provider user paid with
      | "carrier"
      | "mpesa"
      | "mobile_money"
      | "bank_transfer"
    "amount": number, // amount of USD user received
    "amountCrypto": number, // amount of crypto user received
    "network": // network user received USDC/cUSD on
      | "POLYGON"
      | "ETHEREUM"
      | "STELLAR"
      | "AVALANCHE"
      | "SOLANA"
      | "BASE"
      | "CELO"
      | "LISK",
    "asset": "USDC" | "CUSD" | "USDT" | "USDC_E", // asset user received
    "address": string, // address user received USDC/cUSD on
    "orderParams"?: string // Content of a orderParams query parameter provided to a pay widget URL. It might be useful for matching a merchant system user to an order user.
    "hash"?: string, // transaction hash
    "resumeUrl": string, // URL where user can resume his order, it point either to the transfer instructions page or to the status page
  },
  "hash": string, // SHA256 encrypted request.data string to validate a webhook request
};
```

{% endcode %}

**Webhook V2:**[**​**](https://docs.fonbnk.com/docs/pay-widget/webhook#webhook-v2)

Instead of sending hash inside - **WebhookRequest**, we will send it as a request **x-signature** header

```
Request headers:
x-signature: hash (string)
```

**Webhook verification:**[**​**](https://docs.fonbnk.com/docs/pay-widget/webhook#webhook-verification)

We send a hash field in our webhook to protect merchants from fraudulent requests. Each request should be verified by a secret provided in the dashboard.

Here is how it should be checked in pseudocode:

```
request.body.hash === SHA256(stringify(request.body.data), secret)
```

Here is how it should be checked in Node.js:

For Webhook V1 version:

```javascript
import { createHash } from 'crypto';

request.body.hash === createHash('sha256')
   .update(JSON.stringify(request.body.data))
   .update(createHash('sha256').update(__SECRET__, 'utf8').digest('hex'))
   .digest('hex');
```

For Webhook V2 version:

```javascript
import { createHash } from 'crypto';

request 'x-signature' header === createHash('sha256')
   .update(JSON.stringify(request.body))
   .update(createHash('sha256').update(__SECRET__, 'utf8').digest('hex'))
   .digest('hex');
```

{% hint style="info" %}
You can see how to make a signature in multiple programming languages [HERE](/v1/reference/signing-requests.md#request-examples)
{% endhint %}


---

# 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.fonbnk.com/v1/on-ramp/webhook.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.