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

# 📣 Webhooks

> For any notifications related to transactions status and KYC status partners can make use of the webhooks

***

### 📢 Overview

The Capa API provides a webhook-based notification system that allows third-party partners to receive real-time updates whenever specific events occur in our backend systems. This enables partners to stay informed about changes related to their users or transactions and to make necessary updates in their systems accordingly.

### 🔧 How It Works

1. **🔗 Registering a Webhook URL**:\
   Each partner can register a single URL where they wish to receive webhook notifications. This URL must be provided through the designated endpoint. [Set Webhook Settings](/reference/partnerwebhooksettingsv2controller_update)

2. **📬 Receiving Notifications**:\
   Once a URL is registered, partners will receive notifications whenever an event relevant to them occurs, such as:
   * 📝 Updates to a user's KYC (Know Your Customer) status.
   * 💸 Transaction status changes

3. **📡 Notification Handling**:\
   If a notification fails to be delivered (e.g., due to network issues or a problem on the partner's end), the system will automatically retry the delivery up to **5 times** with the following delays:

   | Attempt   | Delay      |
   | --------- | ---------- |
   | 1st retry | Immediate  |
   | 2nd retry | 1 minute   |
   | 3rd retry | 5 minutes  |
   | 4th retry | 10 minutes |
   | 5th retry | 15 minutes |

   If all attempts fail, the notification will be marked as "Failed." You can [list failed notifications](/reference/partnerwebhooknotificationv2controller_listwebhooknotifications), inspect [full delivery details and error payloads](/reference/partnerwebhooknotificationv2controller_getwebhooknotificationdetail), and [manually trigger a retry](/reference/partnerwebhooknotificationv2controller_retry) — up to 3 manual retries per notification. As a fallback, use the [Get KYC Details](/reference/kycpartnercontrollerv2_getuserverificationdetails) or [List Transactions](/reference/transactionpartnerv2controller_listpartnerusertransactions) endpoints to poll for the latest status.

4. **🧪 Mock Testing**:\
   Webhooks **do fire** during mock testing in the staging environment, as long as a webhook URL is configured. This allows you to test your webhook handling end-to-end using the [Mock Testing Guide](/reference/transactionpartnerv2controller_getmocktestingguide).

### 🌐 Source IP Addresses

Webhook events are delivered from the following static IP addresses. If your webhook endpoint is behind a firewall or IP allowlist, add these to your allowed inbound list.

| Environment    | IP Addresses                                       |
| -------------- | -------------------------------------------------- |
| **Staging**    | `44.209.202.213`, `98.86.19.115`                   |
| **Production** | `100.59.133.128`, `34.230.206.95`, `52.72.151.133` |

### 💡 Best Practices

* **🕒 Ensure Availability**: Make sure your webhook URL is always available to receive notifications.
* **🤖 Handle Retries Gracefully**: Implement logic to handle repeated notifications in case of retries.
* **🔍 Validate Data**: Validate all incoming data to ensure it is from a trusted source and in the expected format.
* **✅ Respond with 2xx**: Return a `200` or `2xx` status code promptly to acknowledge receipt. A non-2xx response triggers retries.

***

What’s Next

* [Transaction Events](/docs/transaction-events)
* [KYC Events](/docs/kyc-events)
* [Webhook Settings](/reference/partnerwebhooksettingsv2controller_update)
* [List Webhook Notifications](/reference/partnerwebhooknotificationv2controller_listwebhooknotifications)
* [Retry a Failed Notification](/reference/partnerwebhooknotificationv2controller_retry)