Chargebee and Twilio integrate through Chargebee Webhooks and the Twilio Messages API to send SMS notifications throughout the subscription lifecycle, including plan activations, renewal reminders before billing, failed payment alerts for dunning, and cancellation follow-up messages designed to win back churned subscribers. This integration suits SaaS businesses and subscription box companies running billing through Chargebee that want higher engagement on critical billing notifications than email alone provides. Chargebee's webhook system delivers signed event payloads to your middleware when subscription, invoice, and payment events occur, giving you a real-time trigger for Twilio SMS dispatch.
What You Need Before You Start
Configure Chargebee webhooks by navigating to Settings, then Configure Chargebee, then Webhooks in your Chargebee admin, clicking Add New Webhook, entering your middleware URL, and subscribing to the event types subscription_created, subscription_renewed, subscription_cancelled, payment_failed, and payment_succeeded, and optionally invoice_generated for proactive billing notifications. Copy the Chargebee webhook authentication credentials from the webhook settings page, which can be configured as basic HTTP auth with a username and password that Chargebee sends with every webhook request for validation in your middleware. From Twilio, collect your Account SID and Auth Token, provision an SMS-capable phone number, and register it under an A2P 10DLC campaign in the Twilio Console before sending subscription-related SMS to US customers. Ensure your Chargebee Customer objects include a phone field populated during signup, as Chargebee's billing forms can be extended with custom fields or the phone field can be set programmatically via the Chargebee API at POST https://{site}.chargebee.com/api/v2/customers/{customerId} with a phone parameter.
Step-by-Step Integration Guide
In your middleware webhook handler, validate Chargebee basic auth by checking the Authorization header value against the base64-encoded credentials you configured in the Chargebee webhook settings, returning HTTP 401 for any request that does not match. Parse the event_type field from the Chargebee webhook JSON body to route the event: for subscription_created events extract content.customer.phone and content.subscription.plan_id from the payload, normalize the phone to E.164, and dispatch a Twilio SMS welcoming the customer to the plan name and confirming their next billing date from content.subscription.next_billing_at formatted as a human-readable date. For payment_failed events, extract the customer phone and the amount due from content.invoice.amount_due divided by 100 to convert from cents, and send a Twilio SMS notifying the customer that their payment of the formatted amount failed, including a call to action to update their payment method at your Chargebee self-service portal. For subscription_cancelled events, extract the cancellation reason from content.subscription.cancel_reason_code, fetch the customer phone, and send a Twilio win-back SMS including a promotional offer code generated via the Chargebee coupons API in the SMS body.
Common Issues and How to Fix Them
Chargebee retry logic sends the same webhook event multiple times when your middleware endpoint responds with a 5xx error, and since Twilio SMS dispatch may have succeeded before the error occurred, customers receive duplicate SMS for the same billing event. Implement event ID-based idempotency by extracting the id field from each Chargebee webhook payload, storing it in a processed events database table, and skipping both the Twilio dispatch and returning HTTP 200 when a previously seen event ID arrives. The Chargebee webhook payload for payment_failed does not always include the full customer phone directly in the top-level customer object, as it depends on whether the customer record was enriched with a phone at signup time. Add a fallback API call to GET https://{site}.chargebee.com/api/v2/customers/{customerId} with Basic auth using your Chargebee API key and site name when the phone is null in the webhook payload, retrieving the latest customer record directly. Chargebee sends webhook events in UTC timestamps expressed as Unix epoch integers, and displaying billing dates in SMS without timezone conversion can confuse customers who see billing dates that appear one day off from their local date. Convert the next_billing_at Unix timestamp to the customer's local date using a timezone lookup based on their billing address country before composing the SMS body.
How to Get More from This Integration
Build a pre-renewal SMS reminder sequence by running a daily scheduled job that calls the Chargebee subscriptions API filtering on next_billing_at within the next 7 days, collecting all subscriptions renewing soon, fetching each customer's phone, and sending a Twilio SMS reminding them of the upcoming charge amount and renewal date. Add SMS-driven subscription management by configuring your Twilio inbound number's webhook to accept keywords CANCEL, PAUSE, and UPGRADE from customers, then calling the appropriate Chargebee API endpoint based on the keyword and responding with a Twilio SMS confirmation of the action taken. Create a dunning SMS escalation by tracking the payment_failed event count per customer in a database counter, sending a polite first reminder on the first failure, a more urgent second message on the second failure, and a final cancellation warning SMS on the third failure, mirroring Chargebee's own dunning email sequence with an SMS parallel track. Measure subscription SMS impact by tagging all Twilio SMS dispatches in your database with the Chargebee subscription ID and event type, then joining recovered subscription counts after a payment_failed to the SMS send records to calculate the SMS-attributed recovery rate for your dunning reporting.
Conclusion
Chargebee and Twilio together build a resilient subscription communication layer that reaches customers by SMS at every critical billing moment, reducing churn and improving payment recovery rates. Talk to our team at Telphi Consulting to design and deploy this integration for your Chargebee billing stack.
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.