Recurly and Twilio connect through Recurly Webhooks and the Twilio Messages API to send SMS notifications for subscription activations, invoice payments, payment failures, and dunning events, giving subscription businesses an SMS communication channel alongside Recurly's built-in email notifications. This integration is valuable for businesses with high subscriber volumes running Recurly for billing who need dunning-stage payment failure SMS to complement email and reduce involuntary churn from expired or declined cards. Recurly delivers webhook events via HTTP POST to your middleware endpoint as XML payloads for each subscription and payment lifecycle event.
What You Need Before You Start
Configure a Recurly push notification endpoint by navigating to Integrations in your Recurly admin, selecting Push Notifications, entering your middleware URL, and selecting the notification types new_subscription_notification, renewed_subscription_notification, failed_payment_notification, canceled_subscription_notification, and new_invoice_notification for the key events you want to trigger SMS. Note that Recurly push notification payloads are XML rather than JSON, so your middleware must use an XML parser such as fast-xml-parser in Node.js or ElementTree in Python to extract fields from the event payload. Generate a Recurly API key from the Recurly admin under Integrations, then API Keys, and store it in your middleware as RECURLY_API_KEY for making secondary API calls to fetch subscriber phone numbers not included in the webhook payload. From Twilio, collect your Account SID, Auth Token, and an SMS-capable phone number registered for A2P 10DLC, and confirm that your Recurly account objects include a phone field, which can be set via the Recurly API at PUT https://v3.recurly.com/accounts/{accountCode} with the phone field in the JSON body.
Step-by-Step Integration Guide
In your middleware, parse the incoming Recurly XML webhook payload by reading the root element name to determine the notification type, then extracting the relevant child elements: for new_subscription_notification parse the account element's phone field and the subscription element's plan_code and current_period_ends_at fields. If the account phone is not present in the webhook XML, make a secondary Recurly API call to GET https://v3.recurly.com/accounts/{accountCode} with the Authorization header set to Basic base64(apiKey:) using an empty password, and the Accept header set to application/vnd.recurly.v2021+json to retrieve the full account including the phone field. Normalize the retrieved phone to E.164 format and dispatch the Twilio SMS by calling POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json with Basic authentication, composing the body from the event type: for new_subscription_notification the message announces the plan name and next billing date, while for failed_payment_notification the message states the charge amount and prompts the customer to update their billing information. For dunning-specific failed payment events, check how many prior failed payment notifications you have sent for the same account by querying your middleware database, and escalate the SMS message tone on the second and third failure using progressively more urgent language while following TCPA-compliant messaging standards.
Common Issues and How to Fix Them
Recurly XML push notification delivery does not include an authentication mechanism in the request itself, meaning any actor who knows your middleware URL can POST fabricated payment events that trigger unauthorized Twilio SMS. Restrict your webhook endpoint to Recurly's known IP ranges published in their developer documentation, or implement a shared secret by adding a custom query parameter to your Recurly push notification URL such as ?token={randomSecret} and validating that parameter in every incoming request before processing. Recurly retries failed push notification deliveries up to 10 times over 24 hours when your middleware returns non-2xx, and a temporary Twilio API outage during one of those windows can cause duplicate SMS when the retry fires after recovery. Store each processed Recurly notification type and account code combination with a 24-hour TTL deduplication key in Redis or a database to prevent sending duplicate SMS on retried notifications. The Recurly webhook invoice_amount_in_cents field is an integer in cents, and formatting it as a dollar amount for US customers but as a currency-appropriate format for international subscribers requires knowing the currency code from the invoice's currency field. Read the currency field from the notification XML alongside the amount and use a currency formatting library to produce the correct symbol and decimal placement before embedding the amount in the Twilio SMS body.
How to Get More from This Integration
Build a renewal reminder SMS by running a daily job that calls the Recurly subscriptions API filtering on state=active with current_period_ends_at within the next 7 days, fetching each account phone, and sending a Twilio SMS reminder of the upcoming renewal amount, helping subscribers avoid surprise charges. Create an SMS-based self-service cancel flow by configuring your Twilio inbound number's webhook to detect the keyword CANCEL from subscribers, looking up the subscriber's Recurly account by their phone number in your database, and calling the Recurly API to cancel the subscription, then replying with a Twilio SMS confirmation and a win-back discount code. Extend dunning SMS to include a one-click payment update link by generating a Recurly hosted payment page URL via the Recurly billing info verify endpoint and including the returned token URL in the Twilio SMS so subscribers can update their card with a single tap from the text message. Track SMS dunning effectiveness by logging each failed_payment_notification SMS dispatch alongside the Recurly account code, then querying Recurly monthly for accounts that had a payment failure followed by a successful renewal, attributing the recovery to SMS if the renewal occurred within 48 hours of the SMS dispatch.
Conclusion
Recurly and Twilio together close the gap between billing events and customer awareness, using SMS to ensure payment failures are acted on quickly and subscriptions are retained. Contact Telphi Consulting to implement a Recurly Twilio dunning and notification integration for your subscription platform.
Ready to Transform Your Business Communications?
Get a free consultation with our VoIP experts and discover how we can help you save costs, improve efficiency, and scale your business.
Comments (0)
Join the discussion and share your thoughts (AI-moderated for quality)
Be the first to comment
No comments yet. Share your thoughts below.