Skip to main content
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.

​
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.

​
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.
  • 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 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) 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 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.

​
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.
1

Create the new webhook endpoint

In the Merchant Dashboard, add a new webhook URL and select the target version. Subscribe to the events you need.
2

Deploy and activate the new endpoint

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.
3

Update processing logic

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.
4

Disable the old endpoint

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 for steps. For other products, poll the relevant resource using the documented API, or raise a request using the Support Form.
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.
IP whitelisting is optional. If your infrastructure requires it, add the sandbox and production IP addresses listed in Cashfree IP addresses to your allowlist.