SettleSettle | Developer Hub

Webhook Event Types

SettleSettle delivers webhook events as a standard HTTP POST with a consistent JSON body shape. Here is the list of active events and their exact payload schemas.

Common Payload Envelope#

All webhook bodies contain the following envelope metadata:

Field	Type	Description
`event`	string	The event classification, e.g., `churn.risk.detected`
`webhookId`	string	Unique registered webhook identifier
`appId`	string	The originating SettleSettle Application ID
`payload`	object	Event-specific data and properties
`createdAt`	string	ISO 8601 timestamp of event generation

1. Churn Risk Detected (`churn.risk.detected`)#

Fired instantly when the Predictive Churn AI detects that an end-user exhibits patterns matching critical customer churn parameters (Rule 3).

Event Payload Example#

json

{
  "event": "churn.risk.detected",
  "webhookId": "wh_1234567890",
  "appId": "app_987654321",
  "createdAt": "2026-05-18T07:00:00.000Z",
  "payload": {
    "userId": "user_abc123",
    "email": "customer@domain.com",
    "currentBalance": 0,
    "totalUsageCount": 42,
    "lastActiveAt": "2026-05-17T20:30:00.000Z",
    "daysSinceLastActive": 1,
    "predictedChurnRisk": "HIGH",
    "riskBreakdown": {
      "walletExhaustion": true,
      "insufficientCreditsFrequency": 3,
      "usageDropoffPercentage": 85.0
    }
  }
}

Webhook Event Types

Common Payload Envelope#

1. Churn Risk Detected (churn.risk.detected)#

Event Payload Example#

1. Churn Risk Detected (`churn.risk.detected`)#