API & Developer

Webhook push API

Receiving real-time event notifications from LiftSignals when customer scores change.

What are webhooks?

Webhooks allow LiftSignals to push real-time event notifications to your server — instead of polling the API for changes, your endpoint receives a POST request the moment something happens.

Configuring a webhook endpoint

Go to Settings → Security → Webhooks → Add webhook. Enter your endpoint URL and select which events to subscribe to.

Available events

Event	When it fires
`customer.risk_band_changed`	A customer's churn risk band changes (e.g., Watch → Critical)
`customer.score_updated`	Any change to a customer's churn score (high volume)
`customer.winback_window_opened`	A customer enters their optimal win-back window
`customer.clv_tier_changed`	A customer's predicted CLV tier changes
`workspace.sync_complete`	A data sync finishes successfully
`model.retrain_complete`	Model retraining finishes

Payload format

{
  "event": "customer.risk_band_changed",
  "eventId": "evt_9a2k4j8f3k",
  "timestamp": "2025-04-24T08:14:00Z",
  "workspaceId": "ws_peak_athletics",
  "customer": {
    "id": "cust_9a2k4j",
    "email": "chen.wei@example.com"
  },
  "change": {
    "previousBand": "watch",
    "currentBand": "critical",
    "previousScore": 73,
    "currentScore": 91
  }
}

Signature verification

Every webhook request includes an X-LiftSignals-Signature header (HMAC SHA-256 of the request body using your signing secret). Always verify this signature before processing the webhook.

Retries

If your endpoint returns anything other than a 2xx status code, LiftSignals retries 3 times with exponential backoff (5 seconds, 30 seconds, 5 minutes). After 3 failures, the delivery is marked as failed in your webhook delivery log.

Was this article helpful?