Push Notifications

Push notifications can be used as alerts to keep your systems in sync with actions inside Recurly. Push notifications themselves should not be used as actionable items—Recurly recommends always verifying the data included in a push notification with an API query.

Best Practices

Push notifications are not meant to be actionable and should not be used for critical account functions like provisioning accounts. Use the receipt of a push notification to trigger an API query, validating both the push notification action and the details of the action.

Configuration & Security

Recurly can send push notifications to any publicly accessible server. We recommend using postbin.org as an easy way to capture push notifications while testing. Our notifications support HTTP Basic Authentication to verify the request came from Recurly’s servers. Recurly can only send notifications to port 80 (HTTP) or 443 (HTTPS); other ports are not supported. Push notifications will come from an IP address in the range of 75.98.92.96/28.

Push Notification Details

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 push notification times are in UTC.

Automatic retries

If Recurly receives an error in response to a Push Notification sent to your Push Notification 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+n⁴ seconds where n is the resend attempt number.

Notification Types

Accounts

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.

Subscriptions

New Subscription: Sent when a new subscription is applied to an account.
Updated Subscription: Sent when a subscription is upgraded, downgraded, or the bill cycle date is changed (postponed). 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.

Payments

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 recurly_notification):

protect_from_forgery :except => :recurly_notification