Skip to main content

​
Event Tracking

Track customer behavior events to improve churn prediction accuracy and personalize recovery emails. The more behavioral data Windback has, the better it can predict churn risk and tailor recovery strategies.

​
Endpoint

POST /api/v1/track
Authenticated with your secret API key via the X-API-Key header.

​
Single Event

​
Request Body

​
event
string
required
The event name. Use one of the supported event types below or a custom name.
​
customer_email
string
required
The customer’s email address. Used to associate the event with a customer.
​
properties
object
Arbitrary key-value pairs with additional event data.
​
timestamp
string
ISO 8601 timestamp. Defaults to the current time if omitted.

​
Example Request

curl -X POST https://api.windbackai.com/api/v1/track \
  -H "X-API-Key: sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "event": "feature_used",
    "customer_email": "jane@example.com",
    "properties": {
      "feature": "exports",
      "plan": "pro"
    },
    "timestamp": "2025-12-01T10:00:00Z"
  }'

​
Example Response

{
  "status": "ok"
}

​
Batch Events

Send multiple events in a single request for better performance.

​
Request Body

​
events
array
required
Array of event objects, each with event, customer_email, and optional properties and timestamp.

​
Example Request

curl -X POST https://api.windbackai.com/api/v1/track \
  -H "X-API-Key: sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "event": "login",
        "customer_email": "jane@example.com",
        "timestamp": "2025-12-01T09:00:00Z"
      },
      {
        "event": "feature_used",
        "customer_email": "jane@example.com",
        "properties": { "feature": "dashboard" },
        "timestamp": "2025-12-01T09:05:00Z"
      },
      {
        "event": "support_ticket_opened",
        "customer_email": "jane@example.com",
        "properties": { "subject": "Cannot export data" },
        "timestamp": "2025-12-01T09:30:00Z"
      }
    ]
  }'

​
Supported Event Types

These event types are recognized by the churn prediction engine:
EventDescriptionChurn Signal
loginCustomer logged inPositive
feature_usedCustomer used a featurePositive
subscription_renewedSubscription renewedPositive
subscription_upgradedCustomer upgraded planPositive
subscription_downgradedCustomer downgraded planNegative
support_ticket_openedCustomer opened a support ticketNeutral/Negative
support_ticket_resolvedSupport ticket was resolvedPositive
invoice_paidInvoice was paidPositive
invoice_overdueInvoice is overdueNegative
nps_responseCustomer submitted NPS scoreVaries by score
trial_startedCustomer started a trialNeutral
trial_endedTrial period endedNeutral
refund_requestedCustomer requested a refundNegative
You can send custom event names beyond this list. Custom events are stored and available in analytics but are not used by the churn prediction model until they have sufficient volume for pattern detection.

​
JavaScript Snippet

Track events from your frontend using this lightweight snippet: 
// Windback tracking helper
function trackWindback(event, email, properties) {
  fetch("https://api.windbackai.com/api/v1/track", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": "sk_live_your_secret_key",
    },
    body: JSON.stringify({
      event,
      customer_email: email,
      properties,
    }),
  }).catch(() => {}); // Fire and forget
}

// Usage
trackWindback("feature_used", "jane@example.com", {
  feature: "exports",
  plan: "pro",
});
The example above exposes your secret key in client-side code. For production, proxy tracking calls through your backend server to keep the secret key secure.

​
Best Practices

Start with login, feature_used, and subscription_downgraded. These have the strongest correlation with churn prediction accuracy.
Use snake_case for event names. Avoid variations like featureUsed vs feature_used --- the system treats them as different events.
Properties like feature, plan, duration_seconds, and page add context that improves churn prediction. Avoid sending PII in properties beyond the customer email.
Track events as they happen for the most accurate churn risk scores. If batching, keep the delay under 1 hour.
When importing historical data, use the batch format with explicit timestamps. Send up to 100 events per batch request.
The tracking endpoint is designed for fire-and-forget usage. If a request fails, it is safe to retry or drop --- the churn model handles missing data gracefully.