Definition

Recurly Engage supports the two notification formats Recurly can deliver, each with a dedicated ingestion endpoint:

1. JSON webhooks (recommended) — Recurly's modern webhook endpoint configuration, which delivers events as JSON. Engage enriches each event by querying the Recurly API to sync a full set of subscription, invoice, and billing traits for the user. JSON webhooks also power custom goal tracking and multi-subscription data.
2. XML webhooks (legacy format) — a legacy Recurly endpoint configuration that delivers events as XML. Engage saves only the fields present in the XML payload. This endpoint is used to sync payment failure details, such as failure_type, that are not available through the JSON webhook flow.

Both endpoints use the same authentication credentials and can be configured together. The designated Ingestion Endpoints are:

JSON webhooks:

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

XML webhooks:

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

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

Key benefits

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 JSON webhook endpoint

These steps configure the JSON webhook endpoint in your Recurly account.

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

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

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.

1. Navigate to Settings > Usage Tracking > +Add New Tracker.
2. 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".

Multi-subscription webhook data

If your users can hold multiple subscriptions — for example, a bundle plus an add-on product — you can sync all of a user's subscriptions to Engage, not just the most recent one, and target based on any of them.

To enable:

1. In Recurly Engage, navigate to Settings > Integrations > Recurly.
2. Toggle Multi Subscription Webhooks to On.

Once enabled, every qualifying Recurly webhook event (subscription, account, or invoice events) triggers Engage to fetch all of the user's subscriptions from Recurly and write them to the user's profile as a subscriptions trait. This trait is a complex collection — an array of subscription records, each with the following sub-attributes:

Notes:

• Engage syncs up to 50 subscription records per user per webhook event.
• The subscriptions trait is refreshed on every qualifying webhook event, so the full set stays current as subscriptions are added, changed, or canceled.
• To filter segments on this trait, see Complex collections — including how filters on different sub-attributes are evaluated across all of a user's subscription records.

XML webhooks

XML webhooks use a separate endpoint configuration in Recurly from the JSON webhook above. Configure it only if you want to sync data that is available exclusively in the XML payload (currently: payment failure reasons).

Prerequisites

• The Recurly integration is enabled for your application, with the integration Active in Settings → Integrations → Recurly.
• Use Account Code is enabled in your Recurly connector settings. Engage identifies users on this endpoint by their Recurly account_code, so your Engage user IDs must match your Recurly account codes.

Configure XML webhooks in Recurly

1. In your Recurly dashboard, go to Integrations → Webhooks.
2. Enter the Ingestion Endpoint URL, replacing APP_ID with your application UUID: https://conduit.redfast.com/ingest/APP_ID/update_user_subscription_xml?source=recurly.
3. Set the Format to XML.
4. Enable HTTP Basic Authentication and enter the credentials from Step 1 (Application ID as Username, Application API Key as Password).
5. Subscribe to notification types: Select the notification types you want delivered. Currently, failed_payment_notification is the type Engage processes.

Supported notification types

The failure_type trait enables targeting based on why a payment failed — for example, a winback prompt for users whose payment was declined by the gateway, handled separately from other churn reasons.

Other notification types are delivered to the endpoint and acknowledged without processing.

User identification

Engage identifies users by the account_code field in the XML payload's <account> block, which maps to the visitor's user_id in Recurly Engage. Ensure your Recurly account codes match the user IDs in your Engage application.

Example payload

For reference, Recurly will POST a body like this to the endpoint:

<?xml version="1.0" encoding="UTF-8"?>
<failed_payment_notification>
  <account>
    <account_code>user_123</account_code>
    <email>[email protected]</email>
  </account>
  <transaction>
    <id>a5143c1d3a6f4a8287d0e2cc1d4c0427</id>
    <failure_type>Declined by the gateway</failure_type>
    <status>Declined</status>
    <amount_in_cents type="integer">1000</amount_in_cents>
  </transaction>
</failed_payment_notification>

Response codes

XML webhook limitations

Compared to the JSON webhook endpoint, XML webhooks:

• Save only the fields present in the XML payload. Engage does not query the Recurly API to enrich the user profile from this endpoint.
• Do not support custom goal tracking. Events received on this endpoint cannot increment custom goals, because goal labels follow a different naming convention than XML notification types.
• Do not replace the JSON webhook. To take full advantage of webhook features (rich trait sync via the Recurly API, custom goal increments), keep the JSON webhook endpoint configured. Both endpoints can be configured at the same time, and Recurly can deliver both formats for the same event.

Related: transaction details via the transactions export

Two additional transaction fields are available outside webhooks:

• failure_type is also available in the Recurly transactions export, which Engage can ingest on a daily schedule (contact your CSM to enable transaction export ingestion).
• processor_response_text is not available in webhooks — it is only available via the transactions export (export version 9 or later) or in Recurly's internal logs.