Quickstart

ChurnWarn turns the product, billing, and support signals you already emit into an early-warning churn score per account. This guide gets one event flowing end-to-end.

1. Get an ingest key

Open Settings → API keys in your project and create a key. Both kinds authenticate with the X-Api-Key header; what differs is what they may do:

• Website key (cw_pub_…) — meant to be pasted into your page source. It can only write events and account facts, so it is safe for visitors to read.
• Server key (cw_sec_…) — full access to your project's API. Keep it in your server's environment.

The full key is shown once, at creation. Copy it then; afterwards only its prefix is visible.

2. Send an event

Every event needs an externalAccountId (the customer account id in your system), an eventType, a source, a payload, an occurredAt timestamp and a unique idempotencyKey — the SDKs fill the last three in for you. Pick the path that fits your stack:

curl -X POST https://your-dashboard.example.com/api/events \
-H "X-Api-Key: $CHURNWARN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "externalAccountId": "acct-123",
  "eventType": "feature_used",
  "source": "backend",
  "occurredAt": "'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'",
  "payload": "{\"feature\":\"export_csv\"}",
  "idempotencyKey": "'"$(uuidgen)"'"
}'

3. Verify it landed

Settings → API keys shows a live status next to each key: it flips from Waiting for data to Receiving data as soon as the first call authenticates. Then open your dashboard and find the account by its externalAccountId — new events feed the Engagement and Activity components within a minute. If nothing shows up, check the Security & data masking page for auth and CORS troubleshooting.

Where to go next

• SDK overview — choose between background capture and direct send.
• Direct HTTP & cURL — the full ingest API contract.
• Event map — turn raw event names into the metrics that drive your score.