Skip to main content
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.