Skip to main content

​
Custom Webhook

Use the custom webhook endpoint to connect any payment provider, billing system, or internal tool to Windback.

​
Endpoint

POST https://api.windbackai.com/api/v1/webhooks/custom/<your_public_key>
Your public key starts with pub_ and is found in Settings > API Keys.

​
Payload Format

Send a JSON body with the following fields:
​
customer_email
string
required
The customer’s email address. Used to identify the customer and send recovery emails.
​
customer_name
string
The customer’s display name. Falls back to the email prefix if omitted.
​
event_type
string
required
The type of churn event. One of: cancellation, payment_failed, payment_recovered.
​
cancel_reason
string
Free-text reason for cancellation. Windback AI uses this to select the optimal recovery strategy.
​
mrr
integer
Monthly recurring revenue in cents (e.g., 2999 for $29.99).
​
currency
string
ISO 4217 currency code (e.g., usd, eur, inr). Defaults to usd.
​
provider
string
Name of your payment provider (e.g., paddle, lemonsqueezy, internal). Used for analytics grouping.
​
plan_name
string
The name of the subscription plan the customer was on.
​
tenure_days
integer
Number of days the customer has been subscribed. Used to personalize recovery messaging.

​
Cancel Reason to AI Strategy Mapping

When a cancel reason is provided, Windback AI maps it to the most effective recovery strategy:
Cancel Reason (keywords)AI StrategyDescription
”too expensive”, “cost”, “price”discountOffer a discount or downgrade
”not using”, “don’t use”unused_featureHighlight unused features
”missing feature”, “need X”pain_point_fixAddress the specific gap
”switching”, “competitor”, “alternative”value_recapRecap unique value props
”temporary”, “pause”, “break”pause_optionOffer a subscription pause
”bad experience”, “bug”, “broken”founder_emailPersonal outreach from founder
”no reason”, empty, genericfeedback_requestAsk for feedback with incentive
The AI considers the cancel reason alongside customer tenure, MRR, and behavioral data to select the best combination of strategies. The table above shows the primary strategy; all 9 variants are still generated.

​
Example Request

curl -X POST https://api.windbackai.com/api/v1/webhooks/custom/pub_your_key \
  -H "Content-Type: application/json" \
  -d '{
    "customer_email": "jane@example.com",
    "customer_name": "Jane Smith",
    "event_type": "cancellation",
    "cancel_reason": "Too expensive for our team size",
    "mrr": 4999,
    "currency": "usd",
    "provider": "paddle",
    "plan_name": "Team Pro",
    "tenure_days": 180
  }'

​
Response

The endpoint always returns HTTP 200 with a JSON body: 
{
  "status": "ok"
}

​
Webhook Resilience

The custom webhook endpoint always returns HTTP 200 regardless of internal processing status. This prevents your system from treating transient errors as failures.
Events are queued and processed asynchronously. If processing fails internally, events are retried automatically.

​
Event Type Mapping

event_type ValueWindback Behavior
cancellationCreates a voluntary churn event, triggers AI recovery
payment_failedCreates an involuntary churn event, triggers dunning flow
payment_recoveredMarks a previous churn event as recovered
The customer_email and event_type fields are required. Requests missing these fields will still return 200 but will be silently dropped.

​
Batch Sending

To send multiple events at once, make individual POST requests for each event. A batch endpoint is planned for a future release.
Use the custom webhook for providers like Paddle, Lemon Squeezy, Dodo Payments, Chargebee, or your own internal billing system.