Skip to main content
POST
/
v1
/
webhooks
/
{tenantId}
/
{provider}
Receive alert
curl --request POST \
  --url https://api.example.com/v1/webhooks/{tenantId}/{provider} \
  --header 'Content-Type: <content-type>' \
  --header 'X-API-Key: <x-api-key>' \
  --header 'X-Webhook-Signature: <x-webhook-signature>' \
  --data '
{
  "alert_id": "<string>",
  "title": "<string>",
  "text": "<string>",
  "alert_type": "<string>",
  "priority": "<string>",
  "tags": [
    {}
  ]
}
'

​
Overview

Ingests an alert from an external monitoring provider and creates an incident in CauseFlow AI. Each supported provider has its own expected payload format — see Webhook payload formats for the full schema per provider.
This is a public endpoint — no JWT required. Authentication is via API key and HMAC signature.
Authentication: API key (X-API-Key header) and HMAC-SHA256 signature (X-Webhook-Signature: sha256=... header). Both must be valid for the request to be accepted.

​
Path parameters

​
tenantId
string
required
Your CauseFlow tenant identifier. Found in Settings → General in the dashboard.
​
provider
string
required
The monitoring provider sending the alert. One of: datadog, grafana, cloudwatch, sentry, custom.

​
Request headers

​
X-API-Key
string
required
Your tenant API key. Create one in Settings → API Keys.
​
X-Webhook-Signature
string
required
HMAC-SHA256 signature of the raw request body, prefixed with sha256=. Computed using your webhook signing secret.
​
Content-Type
string
required
Must be application/json.

​
Request body

The request body is provider-specific. Below is the expected payload for Datadog alerts. See Webhook payload formats for all supported providers.
​
alert_id
string
required
Unique identifier for the alert in Datadog.
​
title
string
required
Alert title as configured in Datadog.
​
text
string
required
Full alert message body, including threshold values and context.
​
alert_type
string
required
Datadog alert type. One of: error, warning, info, success.
​
priority
string
Alert priority. One of: P1, P2, P3, P4. Used to seed initial severity classification.
​
tags
array
Array of Datadog tag strings (e.g. ["env:production", "service:checkout"]). Used to enrich incident context.

​
Response

​
201 Created

Alert was accepted and an incident was created (or the existing incident was updated). 
{
  "incidentId": "inc_01HX9VTPQR3KF8MZWBYD5N6JCE",
  "title": "P1 - Checkout service error rate above 5% threshold",
  "severity": "critical",
  "status": "open"
}
FieldTypeDescription
incidentIdstringCauseFlow incident identifier
titlestringIncident title derived from the alert payload
severitystringInitial severity: critical, high, medium, low
statusstringAlways open for newly ingested alerts

​
Error responses

StatusError codeDescription
401invalid_api_keyThe X-API-Key header is missing or does not match a valid key
401invalid_signatureThe X-Webhook-Signature HMAC does not match the request body
409alert_already_existsAlert already ingested — deduplicated by sourceAlertId

​
Examples

# Datadog webhook example
curl https://api.causeflow.ai/v1/webhooks/tenant_01HX9VTP/datadog \
  -X POST \
  -H "X-API-Key: cfak_live_abc123" \
  -H "X-Webhook-Signature: sha256=a4b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "alert_id": "1234567890",
    "title": "P1 - Checkout service error rate above 5% threshold",
    "text": "The error rate for checkout-service has exceeded 5% for 5 consecutive minutes. Current value: 7.3%. Threshold: 5.0%.",
    "alert_type": "error",
    "priority": "P1",
    "tags": ["env:production", "service:checkout", "team:payments"]
  }'