Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.causeflow.ai/llms.txt

Use this file to discover all available pages before exploring further.

If your monitoring tool is not in CauseFlow’s integration catalog, or if you want to send alerts from a custom internal system, you can use the generic webhook endpoint. Any tool that can make an HTTP POST request with JSON can trigger a CauseFlow investigation.

​
Endpoint

POST https://api.causeflow.ai/v1/webhooks/:tenantId/custom
Replace :tenantId with your tenant ID, found in Settings > General.

​
Required headers

HeaderDescription
X-API-KeyYour CauseFlow API key, created in Settings > API Keys
X-Webhook-SignatureHMAC-SHA256 signature of the raw request body

​
Payload format

The request body must be valid JSON. The only required fields are title and description. All other fields are optional but improve triage accuracy. 
{
  "title": "High error rate on payment-service",
  "description": "5xx error rate exceeded 5% for 3 consecutive minutes.",
  "sourceAlertId": "alert-98765",
  "severity": "high",
  "service": "payment-service",
  "environment": "production",
  "tags": {
    "team": "platform",
    "region": "us-east-1"
  },
  "metadata": {
    "errorRate": "5.3%",
    "affectedEndpoints": ["/api/payments", "/api/checkout"]
  }
}
FieldRequiredDescription
titleYesShort description of the alert
descriptionYesDetailed description for triage
sourceAlertIdNoUnique alert ID from your system, used for deduplication
severityNocritical, high, medium, low, or info
serviceNoName of the affected service
environmentNoproduction, staging, development, etc.
tagsNoKey-value pairs for additional categorization
metadataNoAny additional structured data about the alert

​
Generating the HMAC-SHA256 signature

Sign the raw request body with your webhook secret using HMAC-SHA256. The signature must be hex-encoded. 
WEBHOOK_SECRET="your_webhook_secret"
PAYLOAD='{"title":"High error rate","description":"Error rate exceeded threshold."}'

SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $2}')

curl -X POST "https://api.causeflow.ai/v1/webhooks/YOUR_TENANT_ID/custom" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Webhook-Signature: $SIGNATURE" \
  -d "$PAYLOAD"

​
Full curl example

curl -X POST "https://api.causeflow.ai/v1/webhooks/YOUR_TENANT_ID/custom" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Webhook-Signature: YOUR_HMAC_SIGNATURE" \
  -d '{
    "title": "Database connection pool exhausted",
    "description": "All connections in the PostgreSQL pool are in use. New queries are queuing.",
    "sourceAlertId": "alert-112233",
    "severity": "critical",
    "service": "orders-service",
    "environment": "production"
  }'
A successful request returns 202 Accepted with the new incident ID: 
{
  "incidentId": "inc_01j2x...",
  "status": "triaging"
}

​
Deduplication

If you send multiple alerts for the same firing condition, include the same sourceAlertId in each request. CauseFlow deduplicates on this field — subsequent requests with an already-seen sourceAlertId return 409 Conflict and the original incident is not duplicated. 
{
  "error": "duplicate_alert",
  "message": "An incident with sourceAlertId 'alert-98765' already exists.",
  "incidentId": "inc_01j2x..."
}

​
Testing

You can test your webhook setup with curl before connecting your monitoring tool: 
# Generate a test signature
PAYLOAD='{"title":"Test alert","description":"Testing CauseFlow webhook integration."}'
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "YOUR_WEBHOOK_SECRET" | awk '{print $2}')

# Send a test alert
curl -X POST "https://api.causeflow.ai/v1/webhooks/YOUR_TENANT_ID/custom" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Webhook-Signature: $SIGNATURE" \
  -d "$PAYLOAD"
The resulting test incident will appear in the dashboard and go through the full triage pipeline.

​
Receive outbound events

In addition to sending alerts to CauseFlow, you can receive real-time event updates from CauseFlow when investigations progress, incidents are resolved, or remediations are proposed. Today: CauseFlow delivers outbound events via Server-Sent Events (SSE) using the GET /v1/notifications/stream endpoint. Connect to this stream from your backend or dashboard to receive live updates without polling. Coming soon: A programmatic webhook subscription API (POST /v1/webhook-subscriptions) is on the roadmap. This will let you register a delivery URL and receive outbound events as HTTP POST requests without maintaining a persistent SSE connection. For the full list of outbound event types and payload shapes, see the outbound events reference in the API reference section (/api-reference/webhooks/outbound-events).

API reference

Explore the full CauseFlow REST API, including the SSE stream and webhook endpoints.

Monitoring integrations

Connect your monitoring tools for automatic alert ingestion.

Integrations overview

See the full catalog of available integrations.

Security overview

Learn how CauseFlow authenticates and secures webhook traffic.