Developer Guide
Integrations
Build your own integrations with Churnkey webhooks
Webhooks enable Churnkey to push real-time event notifications to your application. Once you’ve registered an endpoint URL, Churnkey will send a secure HTTPS POST request to that URL every time one of your customers completes a Churnkey session. The JSON payload will include session information like their survey response, any freeform feedback they left, and the outcome of the session e.g. subscription pause, cancelation, discount, or if they abandoned the cancellation flow.
Webhooks can be managed from your Churnkey account
Use Cases
Clients use Churnkey webhooks to:
- Update customer profile information in CRMs such as Hubspot or Intercom
- Example: marking every customer who sited “technical difficulties” in their survey response for a tutorial email campaign
- Create a customized Slack thread where customer success teams can discuss next steps for customer retention
- Send “secret plan” offers to customers who already declined offers on Churnkey Please note that for business logic related directly to customer billing and subscriptions, we recommend you use Stripe webhooks. This accounts for the possibility that subscriptions may be modified outside of the Churnkey flow.
Webhook Event Data
As soon as a webhook is enabled, Churnkey will start to stream new event notifications to that URL. These will be HTTPS POST requests with a JSON payload of the below format:
{
"event": "session",
"data": {
"customer": <UP TO DATE CUSTOMER>,
"session": {
"result": "pause", // pause, discount, cancel, abort
"feedback": "Freeform feedback from customer",
"surveyResponse": "Too Expensive",
"mode": "LIVE", // billing mode, LIVE or TEST
"acceptedOffer": {
// details below
"offerType": "PAUSE",
"pauseDuration": 2,
},
// Segment information will be sent if the customer belonged to a segment defined in Churnkey
"segment": {
"name": "My annual customers",
"filter": [
"attribute": "BILLING_INTERVAL",
"operand": "INCLUDES",
"value": ["YEAR"]
]
},
}
}
}If a customer accepts an offer through Churnkey, the data.session object will include an acceptedOffer property with information about the offer they accepted. Depending on the offer type, this object will look different.
Pause offer accepted
{
"offerType": "PAUSE",
"pauseDuration": 2 // pause duration in months
}Discount offer accepted
{
"offerType": "DISCOUNT",
"couponId": "my_coupon_id", // coupon Id in Stripe/Chargebee, discount ID in Braintree
"couponType": "PERCENT", // PERCENT or AMOUNT
"couponAmount": 30,
"couponDuration": 2, // coupon duration in months - null if forever coupon
}Dunning Webhook Data
If you have webhooks enabled and use dunning, Churnkey will stream email event notifications to your webhook URL. There are multiple events for each email based on the recipient’s actions. Potential action values are DELIVERY, BOUNCE, OPEN, CLICK.
{
"event": "dunning",
"data": {
"email": {
"emailTo": "john.doe@gmail.com",
"subject": "Need help with your subscription?",
"from": "info@acme.com",
"action": "DELIVERY", // DELIVERY, BOUNCE, OPEN, or CLICK
"emailCount": 2, // This emails order in the campaign
"emailsRemaining": 3 // Emails remaining in campaign
},
"customer": "cus_XXXXXXXXXXXX"
}
}
