Webhooks API Reference

Use webhooks to receive notifications for events in your ChurnShield account.

Overview

Webhooks allow you to receive notifications when events occur in your ChurnShield account. When an event occurs, we'll send a POST request to the URL you specify with details about the event.

Security

Each webhook request includes a signature header (X-ChurnShield-Signature) that you can use to verify the request came from ChurnShield. The signature is a SHA-256 HMAC of the request body using your webhook secret as the key.

Retry Policy

If your endpoint returns a non-2xx response, we'll retry the webhook up to 3 times with exponential backoff.

Create Webhook

POST/api/webhooks

Example Request

curl -X POST https://api.churnshield.ai/api/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/webhook",
    "events": ["customer.health_score.updated", "customer.status.changed"],
    "description": "Monitor customer health score changes"
  }'

Example Response

{
  "id": "whk_123",
  "url": "https://your-domain.com/webhook",
  "events": ["customer.health_score.updated", "customer.status.changed"],
  "description": "Monitor customer health score changes",
  "created_at": "2024-03-15T12:00:00Z",
  "secret": "whsec_..."
}

Request Body

url - Required. The URL to send webhook events to.

events - Required. Array of event types to subscribe to.

description - Optional. Description of the webhook's purpose.

List Webhooks

GET/api/webhooks

Example Request

curl https://api.churnshield.ai/api/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "webhooks": [
    {
      "id": "whk_123",
      "url": "https://your-domain.com/webhook",
      "events": ["customer.health_score.updated"],
      "description": "Monitor customer health score changes",
      "created_at": "2024-03-15T12:00:00Z"
    }
  ]
}

Event Types

Sent when a customer's health score is updated.

{
  "type": "customer.health_score.updated",
  "data": {
    "customer_id": "cust_123",
    "health_score": 0.85,
    "previous_score": 0.75,
    "factors": {
      "usage": 0.8,
      "support": 0.9,
      "billing": 1.0
    },
    "updated_at": "2024-03-15T12:00:00Z"
  }
}