Webhooks API

Event subscriptions and webhook management

The Webhooks API allows you to subscribe to FluxCascade events and receive real-time notifications at your own endpoints. This enables custom integrations, alerting systems, and workflow automation.

How It Works

Create a webhook endpoint with your URL
Subscribe to specific event types you want to receive
FluxCascade sends HTTP POST requests to your URL when events occur
Verify the signature using your endpoint's secret

Signature Verification

All webhook payloads are signed using HMAC-SHA256. The signature is included in the X-FluxCascade-Signature header. Always verify signatures before processing webhook payloads.

Payload Format

All webhook payloads follow this structure:

{
  "eventType": "sync.completed",
  "timestamp": "2026-01-20T12:00:00Z",
  "data": {
    "jobId": "job_abc123",
    "mappingId": "map_xyz789",
    "status": "completed",
    "stats": {
      "fetched": 100,
      "created": 15,
      "updated": 82,
      "failed": 3
    }
  },
  "metadata": {
    "fluxcascadeEventId": "evt_unique123"
  }
}

Available Event Types

Sync Events

sync.started - Sync job began
sync.completed - Sync finished successfully
sync.failed - Sync encountered an error
sync.partial - Sync completed with some failures

Record Events

record.created - Record was created
record.updated - Record was updated
record.error - Record sync failed

Connection Events

connection.created - New connection added
connection.refreshed - Token refreshed
connection.expired - Token expired
connection.deleted - Connection removed

Mapping Events

mapping.created - Mapping created
mapping.updated - Mapping modified
mapping.deleted - Mapping removed
mapping.activated - Mapping enabled
mapping.deactivated - Mapping paused

Retry Policy

If your endpoint returns a non-2xx status code or times out, FluxCascade will retry the delivery with exponential backoff:

Retry 1: After 1 second
Retry 2: After 2 seconds
Retry 3: After 4 seconds
After 3 failed retries, the delivery is marked as failed

Endpoints that fail 10 consecutive deliveries will be automatically disabled.

{ "eventType": "sync.completed", "timestamp": "2026-01-20T12:00:00Z", "data": { "jobId": "job_abc123", "mappingId": "map_xyz789", "status": "completed", "stats": { "fetched": 100, "created": 15, "updated": 82, "failed": 3 } }, "metadata": { "fluxcascadeEventId": "evt_unique123" } }