Skip to main content

​
Stripe Integration

Connect your Stripe account to automatically detect cancellations, failed payments, and successful recoveries.

​
Setup

1

Copy Your Webhook URL

Find your webhook URL in Settings > Integrations > Stripe. The format is:
https://api.windbackai.com/api/v1/webhooks/stripe/<your_public_key>
Your public key starts with pub_ and is unique to your project.
You can find your public key on the Settings > API Keys page.
2

Add the Webhook in Stripe Dashboard

  1. Go to Stripe Dashboard > Developers > Webhooks
  2. Click Add endpoint
  3. Paste your Windback webhook URL
  4. Select the events listed below
  5. Click Add endpoint
3

Select Webhook Events

Enable the following events in Stripe:
Stripe EventWindback Churn TypeDescription
customer.subscription.deletedVoluntary churnCustomer actively canceled their subscription
invoice.payment_failedInvoluntary churnPayment method declined or expired
invoice.payment_succeededRecoveryPreviously failed payment succeeded

​
Voluntary vs Involuntary Churn

Windback distinguishes between two types of churn to tailor recovery strategies:

Voluntary Churn

The customer intentionally cancels. Triggered by customer.subscription.deleted. Recovery strategies focus on understanding the cancel reason and addressing objections — value recap, downgrade offers, pause options.

Involuntary Churn

The payment fails without customer intent. Triggered by invoice.payment_failed. Recovery strategies focus on updating payment methods — dunning emails, payment update reminders, grace period notifications.

​
Webhook Resilience

Windback webhook endpoints always return HTTP 200 regardless of internal processing status. This prevents Stripe from disabling your webhook due to repeated failures.
Events are queued and processed asynchronously. If processing fails internally, events are retried automatically. You will never lose a churn event due to a transient error.

​
Data Mapping

When Windback receives a Stripe webhook, the following fields are extracted:
Stripe FieldWindback FieldNotes
customer.emailcustomer_emailDecrypted from Stripe customer object
customer.namecustomer_nameFalls back to email prefix if empty
subscription.plan.amountmrrConverted to cents
subscription.plan.currencycurrencyISO 4217 code (e.g., usd)
subscription.plan.nicknameplan_nameStripe plan display name
subscription.createdtenure_daysCalculated from subscription start to cancel

​
Testing with Stripe CLI

You can test the integration locally using the Stripe CLI: 
# Install Stripe CLI and login
stripe login

# Forward events to your Windback webhook
stripe listen --forward-to https://api.windbackai.com/api/v1/webhooks/stripe/pub_your_key

# Trigger a test event
stripe trigger customer.subscription.deleted
stripe trigger invoice.payment_failed
Use Stripe test mode keys during development. Never send test events to a production webhook URL.

​
Verifying the Connection

After setup, you can verify the integration is working:
  1. Trigger a test event using Stripe CLI or the Stripe Dashboard
  2. Check your Windback dashboard for the new churn event
  3. The event should appear within a few seconds with status new
Windback does not currently verify Stripe webhook signatures. The public key in the URL acts as the authentication mechanism. Keep your webhook URL private.