> ## Documentation Index
> Fetch the complete documentation index at: https://www.cashfree.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Reliability and Operations
> Retries, idempotency, Cashfree IP addresses, Payment Gateway webhook migration, and FAQs. Pairs with the payloads and signatures guide.
This page covers what happens after Cashfree delivers a webhook: retry behaviour by product, how to prevent duplicate processing, Cashfree IP addresses for network filtering, and how to migrate Payment Gateway webhook versions without losing events.
## Retry policy
Cashfree retries delivery when your endpoint doesn't return HTTP `200`. Responses outside the `2xx` range, including `3xx` redirects, count as delivery failures.
### Payment Gateway
You can configure a per-endpoint retry policy in the Merchant Dashboard under **Payment Gateway > Developers > Webhooks**. The following policy types are available.
| Policy | Behaviour |
| --------------- | --------------------------------------------------------------------------- |
| **Default** | Retries up to three times at 2, 10, and 30-minute intervals |
| **Fixed** | You choose the retry count (up to 10) and a fixed interval |
| **Exponential** | You choose the retry count (up to 10), a base interval, and a multiplier |
| **Custom** | You choose the retry count (up to 10) and define each interval individually |
### Payouts V2 and Cashgram
Cashfree retries failed deliveries at scheduled intervals. If your endpoint fails more than five consecutive times, the webhook endpoint is disabled automatically. Fix your handler, then re-enable the URL in the Merchant Dashboard.
The exact retry interval schedule for Payouts V2 and Cashgram isn't configurable. Review the Payouts dashboard for current retry timing details, or raise a request using the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).
### Secure ID and PPI
Failed Secure ID and PPI webhook deliveries are retried automatically. Implement idempotent handlers so that duplicate deliveries don't produce duplicate side effects.
***
## Handle duplicate events
Cashfree webhooks follow at-least-once delivery semantics. Network issues, timeouts, or slow handlers can cause the same logical event to arrive more than once. This is expected behaviour.
To avoid duplicate processing:
* Use a stable business identifier (such as `cf_payment_id`, `transfer_id`, or a verification ID) as an idempotency key.
* Before performing any irreversible action, check whether that identifier was already recorded as processed.
* For Payment Gateway webhooks on version `2025-01-01`, also use the `x-idempotency-key` header value as a de-duplication key where applicable.
Design handlers to be idempotent: processing the same event twice must be safe and must produce the same outcome as processing it once.
***
## Best practices
**Security**
* Verify the signature before acting on any payload data. See [Payloads and signature verification](/docs/api-reference/webhooks/payloads-and-signatures).
* Use HTTPS only in production. Don't expose plain HTTP webhook URLs.
* If your network policy requires inbound IP filtering, add the Cashfree IP ranges listed in [Cashfree IP addresses](#cashfree-ip-addresses) to your allowlist.
* Where a timestamp header exists (for example, `x-webhook-timestamp` on Payment Gateway webhooks), reject requests where the timestamp is older than five minutes to limit replay attack risk.
**Reliability and testing**
* Return `200` immediately after signature verification, then queue work to a background worker. Non-`200` responses trigger retries.
* Build for idempotency using unique event or entity IDs and database-level uniqueness constraints.
* Don't assume delivery order. If ordering matters, reconcile state using the relevant resource API (for example, the [Get Order API](/docs/api-reference/payments/latest/orders/get-order)) after the webhook arrives.
* Log the event type, delivery attempt, and processing outcome for every webhook. Set up alerts for sustained delivery failures.
* Use the sandbox environment and test transactions to exercise real payloads before going live.
* Use a tunnelling tool such as [ngrok](https://ngrok.com) to receive webhook events on a local development machine.
* For Payment Gateway, use the **Batch Resend** feature in the Merchant Dashboard to replay events when your endpoint was temporarily unavailable.
***
## Cashfree IP addresses
If your infrastructure restricts inbound traffic by source IP, add HTTPS connections on port `443` from the following Cashfree addresses to your allowlist. This is optional and only required if your network policy enforces it.
| IP address |
| --------------- |
| `52.66.25.127` |
| `15.206.45.168` |
| IP address |
| --------------- |
| `52.66.101.190` |
| `3.109.102.144` |
| `18.60.134.245` |
| `18.60.183.142` |
***
## Payment Gateway webhook migration
When you move from an older Payment Gateway webhook version to a newer one (for example, from `2023-08-01` to `2025-01-01`), use the overlap pattern below to migrate without losing events.
In the Merchant Dashboard, add a new webhook URL and select the target version. Subscribe to the events you need.
Deploy handler logic that returns `200` for the new endpoint URL, then activate the new webhook configuration in the Merchant Dashboard. During this overlap period, Cashfree sends each event to both the old and the new endpoint simultaneously.
Update your handler to parse the new payload format and headers, including `x-idempotency-key` on version `2025-01-01`. Review the product changelog for any breaking field or enum changes before you go live.
After confirming the new endpoint processes events correctly, disable the old webhook configuration in the Merchant Dashboard. Monitor delivery for a period before permanently deleting the old configuration.
***
## Frequently asked questions
The following questions address the most common issues encountered when configuring or maintaining Cashfree webhook integrations.
Yes. Webhook version and REST API version are independent settings. You can enable Payouts V2 webhooks while still using the V1 or V1.2 transfer APIs.
For Payment Gateway, use **Batch Resend** under **Developers > Webhooks > Logs** in the Merchant Dashboard. See [Payment Gateway webhooks](/docs/payments/webhooks) for steps. For other products, poll the relevant resource using the documented API, or raise a request using the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).
The most common causes are:
* Computing the HMAC from a parsed or re-serialised JSON body instead of the raw request body string.
* Using the wrong client secret. For Payouts V2, always use the oldest active secret.
* For Cashgram and Secure ID, incorrect field sorting or concatenation order before hashing.
Confirm that the endpoint URL is publicly accessible over HTTPS, returns `200` for valid signed requests, and isn't blocked by firewall or IP rules. Review webhook delivery logs in the Merchant Dashboard for error details. If the issue continues, raise a request using the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).
IP whitelisting is optional. If your infrastructure requires it, add the sandbox and production IP addresses listed in [Cashfree IP addresses](#cashfree-ip-addresses) to your allowlist.