> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook - Overview and configuration

> Overview and configuration requirements for Waffo Webhook asynchronous event notifications.

Webhook is Waffo’s mechanism for pushing asynchronous event notifications to merchants. When the payment status changes, Waffo sends an HTTPS POST request to the merchant’s `notifyUrl`.

## Why use Webhook

* The **authoritative source** of payment results (higher priority than redirects and polling)
* Asynchronous notifications that do not block the user flow
* Covers all status change events

## Configuration requirements

| Requirement | Description |
| - | - |
| Protocol | HTTPS (TLS 1.2+) |
| Reachability | Accessible via the public internet |
| Signature | Waffo signs the request body using the Waffo private key; the merchant must verify `X-SIGNATURE` using the Waffo public key |
| Response body | `{"message": "success"}` / `{"message": "failed"}` / `{"message": "unknown"}` |

## Webhook request structure

```json theme={null}
{
  "header": {
    "Content-Type": "application/json",
    "X-SIGNATURE": "..."
  },
  "body": {
    "eventType": "PAYMENT_NOTIFICATION",
    "result": { ... }
  }
}
```

## Merchant response

```json theme={null}
{
  "header": {
    "Content-Type": "application/json"
  },
  "body": {
    "message": "success"
  }
}
```

| Response | Description |
| - | - |
| `success` | Successfully received and processed |
| `failed` | Processing failed; Waffo will retry |
| `unknown` | Status unknown; Waffo will retry |

## Configuration methods

Payment notifications and global business notifications use different configuration methods:

See [Configure refund and Chargeback notification URLs](/docs/en/developer-docs/getting-started/notification-url-configuration.md) for Dashboard steps and URL requirements.

## Local development

Use an intranet tunneling tool to expose a local port as a public URL:

```bash theme={null}
# cloudflared
cloudflared tunnel --url http://localhost:3000

# ngrok
ngrok http 3000
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.