---
title: "CDC Webhooks"
---

# CDC Webhooks

:::caution[Planned: CDC webhooks]
CDC webhooks are planned for HeliosDB Full. The current release does not capture
changes from the write-ahead log for delivery or call HTTP endpoints, and it does not
accept the CDC stream statements on this page yet. This page describes the planned design. Today, `SHOW CDC EVENTS [LIMIT n]` returns the most recent
INSERT, UPDATE and DELETE events from the server's in-memory change-event log (see the
[CDC tutorial](/docs/full/tutorials/intermediate/05-cdc-events/)).
:::

---

## Overview

HeliosDB's planned CDC-to-Webhook integration streams database changes (INSERT, UPDATE, DELETE) to external systems through HTTP webhooks, with exactly-once delivery, a circuit breaker and monitoring.

## Key Capabilities

| Capability | Description | Availability |
|------------|-------------|--------|
| **Event Capture** | WAL-based Change Data Capture | Planned |
| **Event Delivery** | HTTP webhooks with retry | Planned |
| **Delivery Guarantee** | Exactly-once semantics | Planned |
| **Event Filtering** | Table/operation/column filters | Planned |
| **Event Transformation** | JSONPath, Jinja2 templates | Planned |
| **Circuit Breaker** | Automatic failure detection | Planned |
| **Monitoring** | Prometheus metrics, dashboards | Planned |

## Performance Characteristics

The figures below are indicative, measured on representative fixtures; reproduce on your own hardware.

| Metric | Value |
|--------|-------|
| **Event Capture Rate** | 100K events/sec |
| **Webhook Delivery Latency (P50)** | 5-10ms |
| **Webhook Delivery Latency (P99)** | 30-50ms |
| **Delivery Success Rate** | 99.9% |
| **Exactly-Once Guarantee** | 100% (within 24hr window) |
| **Max Concurrent Webhooks** | 10,000 |
| **Queue Capacity** | Unlimited (disk-backed) |

## Architecture

```
                    CDC-to-Webhook Pipeline

  ┌─────────────┐     ┌─────────────────┐     ┌──────────────┐
  │  Database   │ --> │   WAL/CDC       │ --> │   Event      │
  │  Changes    │     │   Processor     │     │   Queue      │
  └─────────────┘     └─────────────────┘     └──────────────┘
                                                     │
                                                     v
  ┌─────────────┐     ┌─────────────────┐     ┌──────────────┐
  │  External   │ <-- │   Webhook       │ <-- │   Worker     │
  │  Endpoints  │     │   Delivery      │     │   Pool       │
  └─────────────┘     └─────────────────┘     └──────────────┘
        │                    │                      │
        v                    v                      v
  ┌─────────────────────────────────────────────────────────┐
  │              Monitoring & Observability                  │
  │  (Prometheus metrics, Grafana dashboards, Audit logs)   │
  └─────────────────────────────────────────────────────────┘
```

## Feature Highlights

### 1. WAL-Based Event Capture

Capture database changes directly from the Write-Ahead Log for maximum performance and minimal overhead.

### 2. Exactly-Once Delivery

Idempotency keys ensure each event is delivered exactly once, even in the presence of retries and failures.

### 3. Circuit Breaker Protection

Automatic failure detection prevents cascading failures when webhook endpoints are unhealthy.

### 4. Flexible Filtering

Filter events by:
- Table name
- Operation type (INSERT, UPDATE, DELETE)
- Column changes
- Custom predicates

### 5. High Throughput

Process 100K+ events per second with low latency and high reliability.

## Quick Example

### SQL Interface

```sql
-- Create a CDC stream to Kafka
CREATE CHANGE DATA CAPTURE ON users
  TO KAFKA 'localhost:9092' TOPIC 'users-changes'
  FORMAT JSON;

-- Monitor the stream
SHOW CDC STREAMS;
SHOW CDC STREAM STATUS users_cdc_stream;

-- Pause during maintenance
ALTER CDC STREAM users_cdc_stream PAUSE;

-- Resume
ALTER CDC STREAM users_cdc_stream RESUME;
```

## Use Cases

| Use Case | Description |
|----------|-------------|
| **Real-time Analytics** | Stream changes to analytics systems |
| **Event-Driven Architecture** | Trigger downstream services on data changes |
| **Data Sync** | Keep external systems in sync with database |
| **Audit Logging** | Capture all changes for compliance |
| **Cache Invalidation** | Invalidate caches when data changes |
| **Search Indexing** | Update search indexes in real-time |

## Related Documentation

- [User Guide](https://www.heliosdb.com/docs/full/features/webhooks/user_guide/) - Comprehensive CDC webhook guide
- [Troubleshooting](https://www.heliosdb.com/docs/full/features/webhooks/troubleshooting/) - Common issues and solutions
- [SQL CDC Commands](https://www.heliosdb.com/docs/full/features/sql-interface/sql_command_extensions/#change-data-capture-cdc) - SQL interface

---

**See Also**: HeliosDB Feature Index