Webhooks (JSON & XML)

Configure Recurly webhooks to receive real-time notifications about account events — with HTTP Basic Authentication, automatic retries, signature verification, and support for JSON and XML payloads.

Webhooks notify your systems and partner applications of events within Recurly in real time. When an event occurs — such as an account being opened — Recurly attempts to send a notification to the endpoint(s) you specify. Webhooks are configured in the Admin UI and work best alongside the Recurly API to ensure data integrity and synchronization.

Available on all Recurly plans

1Definition 2Key benefits 3Key details

Configuration noteWebhooks are configured in the Recurly Admin UI and cannot be configured via API. Don't rely on webhooks alone for critical functions — use them alongside API responses to ensure data integrity.

Definition

Webhooks are event-driven notifications that alert your systems and partner applications when something happens in Recurly. They're not standalone actions — they signal that an event occurred, and your systems should use the Recurly API to retrieve or confirm the relevant data. Use them in tandem with API responses for reliable, synchronized data handling.

Key benefits

Real-time updates Get notified of significant events in Recurly as they happen — account changes, payment events, subscription lifecycle, and more.

Enhanced security HTTP Basic Authentication and signature verification confirm that notifications originate from Recurly and haven't been tampered with.

Automatic retries Failed webhook deliveries are retried automatically, with exponentially increasing intervals between attempts.

Payload format flexibility Choose JSON or XML per endpoint. JSON is recommended for its lightweight format and alignment with modern best practices.

Key details

Configuration and security

Webhooks are configured in the Recurly Admin UI. Recurly supports HTTP Basic Authentication to confirm that requests originate from Recurly's servers. Always check the IP Allowlist documentation for the current list of Recurly IP addresses and configure your endpoint to accept only those IPs.

Apache with ModSecurityIf you're using Apache with ModSecurity, you may need to disable rule #990011 in mod_security to unblock webhook delivery.

Webhook storage and timestamps

Each webhook notification is stored for 15 days and is accessible through the Admin Console, which also shows failure reasons. Webhook timestamps are in UTC but are translated to your site's configured timezone when viewed in the application.

Automatic retries

If Recurly receives an error in response to a webhook, the notification is retried. After ten failed attempts, Recurly stops sending that notification.

The interval between retries follows this formula: 10 + x * 2^(x+5) seconds, where x is the current attempt number. The first few retries happen quickly, with intervals growing exponentially from there.

Manual retries

Individual notifications can be retried by clicking them and pressing Retry.

To bulk retry paused or failed notifications, use the appropriate button in the Webhook Actions dropdown.

Notification types

Webhooks can be configured per endpoint — you can opt in to only the notification types relevant to that endpoint. For example, you can configure one endpoint to receive only new account notifications while excluding account update notifications.

For the full list of notification types, see the Webhooks Developer Docs.

JSON vs. XML payloads

Each webhook endpoint can be configured to receive JSON or XML payloads — not both. Recurly recommends JSON for its lightweight format and alignment with modern best practices.

Signature verification

For JSON payloads, Recurly signs each notification and includes the signature in a recurly-signature request header. Verifying this signature confirms the notification came from Recurly and hasn't been modified in transit.

CSRF protection in Rails applications

For Rails applications with protect_from_forgery enabled, disable forgery protection for the action that listens for Recurly webhook notifications.

Developer documentation

For full implementation details, see the Webhooks developer documentation.

Updated 7 days ago

Did this page help you?