---
title: "Webhooks — Real-Time Retention Event Notifications"
description: "Connect Churnkey to your tech stack with real-time webhooks for cancellation, payment, subscription, and customer events."
canonical: "https://churnkey.co/feature/webhooks"
category: "feature"
related:
  - /feature/cancel-flows.html.md
  - /feature/payment-recovery/index.html.md
  - /integrations/index.html.md
  - /sdk-overview.html.md
last_updated: "2026-07-14"
---

# Webhooks

## Overview

Connect Churnkey to your entire tech stack with real-time webhooks. Get instant notifications for every retention event and trigger automated workflows across your systems.

## Webhook Events

### Cancellation Events
- `cancellation.attempted` - User starts cancel flow
- `cancellation.saved` - Customer retained successfully
- `cancellation.completed` - Customer churned
- `cancellation.feedback` - Feedback submitted
- `cancellation.offer_accepted` - Retention offer accepted

### Payment Events
- `payment.failed` - Payment failure detected
- `payment.recovered` - Failed payment recovered
- `payment.retry_scheduled` - Retry attempt planned
- `payment.method_updated` - Card/account updated
- `payment.dunning_exhausted` - Recovery failed

### Subscription Events
- `subscription.paused` - Pause initiated
- `subscription.resumed` - Pause ended
- `subscription.downgraded` - Plan reduced
- `subscription.reactivated` - Win-back successful
- `subscription.modified` - Any plan change

### Customer Events
- `customer.health_changed` - Health score update
- `customer.risk_detected` - Churn risk identified
- `customer.segment_entered` - Segment membership
- `customer.milestone_reached` - Usage milestone
- `customer.feedback_analyzed` - AI insights ready

## Webhook Payload

### Standard Structure
```json
{
  "id": "evt_1234567890",
  "type": "cancellation.saved",
  "created": 1678901234,
  "data": {
    "customer_id": "cus_ABC123",
    "subscription_id": "sub_XYZ789",
    "reason": "too_expensive",
    "offer_accepted": "20_percent_3_months",
    "retained_mrr": 9900,
    "metadata": {}
  }
}
```

### Security Features
- HMAC signature verification
- Webhook secret rotation
- IP allowlisting
- Retry logic
- Idempotency keys

## Integration Use Cases

### CRM Updates
- Update customer records
- Log retention activities
- Track save history
- Sync feedback data
- Trigger workflows

### Analytics Platforms
- Send retention events
- Track conversion funnels
- Measure offer performance
- Analyze cohort behavior
- Attribution modeling

### Communication Tools
- Trigger thank you emails
- Alert account managers
- Update support tickets
- Notify sales teams
- Schedule follow-ups

### Internal Systems
- Update dashboards
- Adjust forecasts
- Calculate commissions
- Generate reports
- Audit compliance

## Configuration Options

### Endpoint Management
- Multiple endpoints
- Environment separation
- URL validation
- Health monitoring
- Automatic disabling

### Event Filtering
- Subscribe to specific events
- Exclude event types
- Filter by criteria
- Sample percentage
- Test mode

### Delivery Settings
- Retry configuration
- Timeout settings
- Batch options
- Rate limiting
- Priority levels

## Advanced Features

### Webhook Testing
- Test event generation
- Payload preview
- Endpoint validation
- Error simulation
- Debug mode

### Monitoring & Logs
- Delivery status
- Response tracking
- Error details
- Latency metrics
- Success rates

### Transformations
- Custom headers
- Payload mapping
- Field filtering
- Format conversion
- Enrichment rules

## Security & Reliability

### Authentication
- HMAC-SHA256 signatures
- OAuth support
- API key validation
- Certificate pinning
- Token rotation

### Delivery Guarantees
- At-least-once delivery
- Automatic retries
- Exponential backoff
- Dead letter queue
- Manual replay

### Compliance
- GDPR compliance
- Data minimization
- Encryption in transit
- Audit logging
- Right to deletion

## Common Integrations

### Marketing Automation
- HubSpot workflows
- Marketo programs
- Pardot campaigns
- ActiveCampaign
- Customer.io

### Analytics
- Segment tracking
- Mixpanel events
- Amplitude cohorts
- Google Analytics
- Heap automation

### Data Warehouses
- Snowflake sync
- BigQuery streaming
- Redshift updates
- Databricks
- PostgreSQL

### Custom Applications
- Internal dashboards
- Billing systems
- Reporting tools
- Alert systems
- Data pipelines

## Implementation Guide

### Quick Start
```javascript
// Verify webhook signature
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return hash === signature;
}

// Handle webhook event
app.post('/webhooks/churnkey', (req, res) => {
  if (!verifyWebhook(req.body, req.headers['x-churnkey-signature'], WEBHOOK_SECRET)) {
    return res.status(401).send('Unauthorized');
  }

  const event = req.body;

  switch(event.type) {
    case 'cancellation.saved':
      // Handle saved customer
      break;
    case 'payment.recovered':
      // Handle recovered payment
      break;
    // ... handle other events
  }

  res.status(200).send('OK');
});
```

### Best Practices
1. Always verify signatures
2. Implement idempotency
3. Respond quickly (< 5s)
4. Handle retries gracefully
5. Log everything

### Error Handling
1. Return proper status codes
2. Implement circuit breakers
3. Use exponential backoff
4. Monitor endpoint health
5. Alert on failures

## Monitoring & Debugging

### Webhook Dashboard
- Real-time event stream
- Delivery status
- Error tracking
- Performance metrics
- Testing tools

### Troubleshooting
- Event replay
- Request inspection
- Response debugging
- Signature verification
- Timeout analysis

## Results

Companies using Webhooks report:
- **100% automation** of retention workflows
- **80% reduction** in manual data entry
- **Real-time** system synchronization
- **5x faster** response to retention events
- **Zero data** silos across tools

## Pair with the Open Source SDK + MCP

React to retention events in real time — in your app, your warehouse, or your AI agent.

### `@churnkey/react`

The open-source React SDK ships the cancel flow as a drop-in component, a headless hook, or a framework-agnostic core state machine. Use it standalone or paired with webhooks for closed-loop retention. [Repository](https://github.com/churnkey/sdk) · [Docs](https://sdk.churnkey.co).

### `@churnkey/mcp`

The open-source [MCP server](/feature/mcp.html.md) brings Churnkey sessions, analytics, and DSR into Claude, Cursor, and other MCP-compatible AI agents. Install with `npx -y @churnkey/mcp`. [npm](https://www.npmjs.com/package/@churnkey/mcp).

See the [SDK overview](/sdk-overview.html.md) for full details.

## Get Started

Ready to connect Churnkey to your tech stack? [Get Started](/pricing/churnkey-pricing.html.md) or [Talk With Us](https://churnkey.co/schedule-a-demo) to learn how Webhooks can automate your retention operations.

## Documentation

For webhook setup and payload details, see the [Webhooks Documentation](https://docs.churnkey.co/data-integrations/webhooks/).

## FAQ

### What events can I subscribe to?
Churnkey webhooks cover four major event categories: cancellation events (attempted, saved, completed, feedback, offer accepted), payment events (failed, recovered, retry scheduled, method updated, dunning exhausted), subscription events (paused, resumed, downgraded, reactivated, modified), and customer events (health changed, risk detected, segment entered, milestone reached, feedback analyzed). You can subscribe to any combination of these events.

### How are webhooks secured?
Every webhook delivery includes an HMAC-SHA256 signature in the request header that you verify against your webhook secret. Additional security features include webhook secret rotation, IP allowlisting, OAuth support, certificate pinning, and idempotency keys to prevent duplicate processing.

### What is the retry policy for failed webhook deliveries?
Churnkey uses at-least-once delivery with automatic retries and exponential backoff. If your endpoint is temporarily unavailable, failed deliveries are retried multiple times over an extended period. Events that exhaust all retries are placed in a dead letter queue and can be manually replayed from the webhook dashboard.

### Can I filter webhooks by event type?
Yes. You can subscribe to specific event types, exclude others, filter by custom criteria, set a sample percentage for high-volume events, and use test mode to validate your integration before going live. Each endpoint can have its own independent event filter configuration.

### What payload format do webhooks use?
All webhooks are delivered as JSON POST requests with a standard structure that includes a unique event ID, event type, Unix timestamp, and a data object containing event-specific fields such as customer ID, subscription ID, reason, offer details, and retained MRR. Custom metadata you attach to customers or subscriptions is also included.

## Related

- [Cancel Flows](/feature/cancel-flows.html.md) — The retention flows that generate cancellation webhook events
- [Payment Recovery](/feature/payment-recovery/index.html.md) — Failed payment and recovery events delivered via webhooks
- [Integrations](/integrations/index.html.md) — Pre-built integrations that use webhooks under the hood
- [Customer Timelines](/feature/customer-timelines.html.md) — Visual timeline of the events webhooks deliver
- [Session Recordings](/feature/session-recordings.html.md) — Pair event data with visual session playback