Webhooks

Overview

StackFlow supports both inbound webhooks (receiving alerts and events from external systems) and outbound webhooks (notifying external systems of StackFlow events). All webhook payloads are JSON. Outbound webhooks are signed with HMAC-SHA256 using a shared secret stored in AWS Secrets Manager.

Inbound Webhooks

Inbound webhooks allow external systems (monitoring tools, CI/CD pipelines, cloud providers) to push events into StackFlow. Each inbound webhook is assigned a unique URL and an optional secret for signature verification.

# Create an inbound webhook endpoint
curl -X POST   https://your-instance.stackflow-tech.com/prod/api/webhooks/inbound   -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json"   -d '{
    "name": "Datadog Alerts",
    "description": "Receive Datadog monitor alerts and create incidents",
    "action": "create_incident",
    "field_mapping": {
      "short_description": "{{alert.title}}",
      "priority": "{{priority_map[alert.priority]}}",
      "category": "monitoring"
    },
    "filters": [
      {"field": "alert.status", "operator": "eq", "value": "triggered"}
    ],
    "secret_enabled": true
  }'

{
  "id": "wh_in_abc123",
  "url": "https://your-instance.stackflow-tech.com/prod/api/webhooks/inbound/wh_in_abc123",
  "secret": "whsec_XXXXXXXXXXXXXXXX",
  "name": "Datadog Alerts",
  "action": "create_incident",
  "created_at": "2026-05-19T15:00:00Z"
}

Outbound Webhooks

Outbound webhooks fire when StackFlow events occur and POST to external URLs. Configure them in Admin → Integrations → Outbound Webhooks or via the API.

# Create an outbound webhook
curl -X POST   https://your-instance.stackflow-tech.com/prod/api/webhooks/outbound   -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json"   -d '{
    "name": "Notify PagerDuty on P1 Incident",
    "url": "https://events.pagerduty.com/v2/enqueue",
    "events": ["incident.created", "incident.priority_changed"],
    "filters": [{"field": "incident.priority", "operator": "eq", "value": "P1"}],
    "headers": {"Content-Type": "application/json"},
    "sign_payloads": true,
    "active": true
  }'

Outbound webhook payload shape:

{
  "event": "incident.created",
  "timestamp": "2026-05-19T15:05:00Z",
  "stackflow_instance": "your-instance",
  "data": {
    "id": "INC0001235",
    "short_description": "API gateway 502 errors spike",
    "priority": "P1",
    "state": "new",
    "url": "https://your-instance.stackflow-tech.com/incidents/INC0001235"
  }
}

Payload Signing & Verification

When sign_payloads: true, StackFlow adds an X-StackFlow-Signature header to every outbound request. Verify it on the receiving end:

import hmac
import hashlib

def verify_webhook(payload_bytes: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload_bytes,
        hashlib.sha256
    ).hexdigest()
    actual = signature_header.replace("sha256=", "")
    return hmac.compare_digest(expected, actual)

# Usage
is_valid = verify_webhook(
    request.body,
    request.headers["X-StackFlow-Signature"],
    "your_webhook_secret"
)

Retry Logic

Outbound webhooks are delivered with exponential backoff retry logic. Failed deliveries (non-2xx response or timeout) are retried up to 5 times:

After 5 failures, the webhook delivery is marked as failed and an alert is sent to the webhook owner. Failed deliveries can be replayed from the webhook dashboard.

Webhook Event Types

Field Reference