Connect Recurly webhooks to Recurly Engage to keep your users' subscription data up to date in real time. This page covers the endpoint, the authentication credentials, the events to subscribe to, and how to track Recurly events as custom goals.

Available on all Recurly plans

1Definition 2Key benefits 3Key details

Definition

A Recurly webhook is an automatic HTTP POST notification that Recurly sends in real time to a specified URL, called the Ingestion Endpoint, when a subscription-related event occurs. Examples include a subscription being activated, updated, canceled, or expiring. The request payload is a JSON object with the details of the event, following the Recurly subscription notification format.

Key benefits

Real-time data sync Get immediate notification of subscription status changes, so your system's user traits are updated promptly.

Enhanced user experience Take timely action based on subscription events, such as adjusting service access, triggering tailored communication, or managing lifecycle campaigns.

Data consistency Keep your Recurly billing data and your internal user management system synchronized.

Key details

Ingestion Endpoint

The designated Ingestion Endpoint for subscription change events is:

https://conduit.redfast.com/ingest/APP_ID/update_user_subscription?source=recurly

The APP_ID is a unique identifier (universally unique identifier, or UUID) for your application.

Configure the webhook endpoint

These steps configure the webhook endpoint in your Recurly account.

Locate your authentication credentials

You need two credentials for authentication, listed below.

Username: Your Application ID (APP_ID), which is the UUID in the Ingestion Endpoint URL.
Password: Your Application API key, available in Pulse under Settings → Application.

Configure the Recurly webhooks endpoint

Make sure the endpoint's payload format is set to JSON. Then open the Webhook Endpoint configuration screen in your Recurly application's settings and complete the actions below.

Enter the Ingestion Endpoint URL: Input the complete URL, replacing APP_ID with your application UUID: https://conduit.redfast.com/ingest/APP_ID/update_user_subscription?source=recurly.
Configure authentication: Enable HTTP Basic Authentication for the endpoint.
1. Enter your Application ID as the Username.
2. Enter your Application API Key as the Password.
Subscribe to events: Select the subscription-related events you want to track in real time. For a comprehensive update, we recommend subscribing to all relevant subscription change events, such as:
1. subscription.created
2. subscription.updated
3. subscription.canceled
4. subscription.renewed
5. subscription.paused
6. subscription.resumed
7. subscription.expired
8. charge_invoice.paid
9. charge_invoice.past_due

Enable Recurly events as custom goals

Engage supports using specific Recurly webhook events to increment custom goals for end users. A Recurly Subscription Management user can configure the webhook to fire on these events and track them as custom goal completions.

Engage automatically supports the following two Recurly webhook events as custom goals:

subscription.canceled
billing_info.updated

To enable tracking for these custom goals, make sure you've subscribed to the relevant events (subscription.canceled and billing_info.updated) in the Recurly webhook endpoint configuration (Step 2, item 3).

Advanced usage and custom goals

To implement additional Recurly events as custom goals beyond the default two, create usage trackers in Engage with the proper label attributes. These labels must match the Recurly webhook payload, using the convention object_type.event_type. Learn more about usage tracking.

Navigate to Settings > Usage Tracking > +Add New Tracker.
Create a new custom tracker by adding the name, label (be sure to match the Recurly webhook payload), and description of the tracker. Make sure the tracker type is set to "Custom".