Webhooks can be used as alerts to keep your systems in sync with actions inside Recurly. Webhooks themselves should not be used as actionable items— please see Best Practices below for more information on working with webhooks.
Recurly can send webhooks to any publicly accessible server. When an event in Recurly triggers a webhook (e.g., an account is opened), Recurly will attempt to send this notification to the endpoint you specify.
Recurly only considers a notification delivered if it receives a timely response with a successful status code. In other words:
- Your endpoint must be reachable at ports
443(HTTPS) (Recurly does not support other ports).
- Your endpoint must respond within 5 seconds
- Your endpoint must respond with a
2XXstatus code (e.g.,
204, etc). Recurly does not follow redirects or consider them successful responses.
Webhooks are not actionable on their own and should not be used for critical functions like provisioning accounts. The API response from an original action (ie signup, one time purchase) can be used to provision the account and store the state/details behind the action locally. The state/details of a user should be maintained in your internal database, and assumed unchanged unless a change of state is indicated with a webook. Use the receipt of a webhook to trigger an API query to validate the push notification details against the current API data.
Recurly webhooks may be retried or sent multiple times if the delivery status is considered failed. Please make sure your endpoint can receive the same notification multiple times and in the wrong order.
For example, an account can close and we will send a notification for this. If delivery fails, the notification will be sent again later. In the meantime, the account could reopen (triggering another push notification). If your endpoint begins working again, it may receive the closed account notification after the account was reopened). Make sure that if your application takes action on closed accounts, that it verifies the account is still closed by issuing an API request.
Configuration & Security
If Recurly fails to deliver a webhook, it will retry it (see Automatic retries, below).
Webhooks support HTTP Basic Authentication to verify the request came from Recurly’s servers.
Webhooks will come from any of the following IP addresses:
You may refuse other IP addresses from your endpoint configuration.
We recommend using http://requestb.in/ as an easy way to capture webhooks for initial testing.
Notifications are never combined. For example, if user signs up for a new subscription and this triggers a payment, you will receive two separate notifications (one for the subscription and one for the payment).
Notifications older than a month are periodically deleted. All web hook times are in UTC.
If Recurly receives an error in response to a Webhook sent to your Webhook URL, the notification will be retried. After ten failed attempts, Recurly will stop trying to send the failed notification. Notifications are sent in the order in which they were created. The interval between retries is 10+n4 seconds where n is the resend attempt number.
- New Account
- Sent when a new account is created.
- Canceled Account
- Sent when an account is closed.
- Billing Info Updated
- Sent when billing information is successfully created or updated on an account.
- New Invoice
- Sent when a new invoice is created.
- Closed Invoice
- Sent when an invoice is either marked as failed or paid.
- Past Due Invoice
- Sent when an invoice has gone past due.
- New Subscription
- Sent when a new subscription is activated on an account.
- Updated Subscription
- Sent when a subscription is modified. This may include upgrades, downgrades, price/quantity changes, or a change in the bill cycle date (postponement). The notification is sent after the modification is performed. If you modify a subscription and it takes place immediately, the notification will also be sent immediately. If the subscription change takes effect at renewal, then the notification will be sent when the subscription renews.
- Expired Subscription
- Sent when a subscription is terminated or a previously canceled subscription has reached the end of its bill cycle.
- Canceled Subscription
- Sent when a subscription has been canceled and will not renew. The subscription state is set to canceled but the subscription is still valid until the expires-at date. The Expired Subscription notification is sent when the subscription is completely terminated.
- Renewed Subscription
- Sent whenever a subscription renews. This notification is sent regardless of a successful payment being applied to the subscription–it indicates the previous term is over and the subscription is now in a new term. If you are performing metered or usage-based billing, use this notification to reset your usage stats for the current billing term.
- Reactivated Account
- Sent when a subscription is reactivated after having been canceled.
- Successful Payment
- Sent when a payment is successfully captured.
- Failed Payment
- Sent when a payment attempt is declined by the payment gateway.
- Successful Refund
- Sent when a payment has been refunded. Failed refund attempts do not generate a notification.
- Void Payment
- Sent when a payment has been voided before it is settled.
Cross Site Request Forgery (CSRF) for Rails applications
Many Rails applications enable forgery protection (
protect_from_forgery). You must disable
protect_from_forgery for the action you setup to listen for changes from Recurly. In your controller, use the following line (assumes your listening action is named
protect_from_forgery :except => :recurly_notification