Integration Studio

Webhook Management

Manage outbound webhooks — configure target URLs, event subscriptions, HMAC signing, retry policies, payload filtering, and view the delivery log.

FlowOS can deliver real-time event payloads to any HTTP endpoint via outbound webhooks. Configure webhooks at Integrations → Webhooks. Inbound webhooks (receiving from external systems) are handled by SDK webhook handler artifacts — see Artifact Types.

Creating a Webhook

POST

/api/v1/webhooks

Create a new outbound webhook.

Field	Type	Required	Default	Description
name	string	required	—	Display name.
url	string	required	—	Target URL. Must be HTTPS.
events	string[]	required	—	Event types to subscribe to. Use wildcard patterns like "incident." or "audit.".
secret	string	optional	—	HMAC signing secret. If set, every delivery includes an X-FlowOS-Signature-256 header.
headers	object	optional	—	Additional HTTP headers sent with every delivery (e.g., Authorization).
filter	object	optional	—	Payload filter — only deliver events matching these conditions.
retries	number	optional	3	Number of retry attempts on failure.
retry_strategy	enum	optional	"exponential"	fixed \| exponential (2s, 4s, 8s backoff).
timeout_ms	number	optional	10000	Request timeout in ms.
status	enum	optional	"active"	active \| paused

Event Payload Format

json

// Every delivery is a POST with Content-Type: application/json
{
  "id": "evt_01HX...",           // unique delivery ID
  "webhook_id": "wh_01HX...",
  "event": "incident.created",   // event type
  "timestamp": "2026-06-01T10:23:45Z",
  "workspace_id": "ws_01HX...",
  "data": {
    // full resource payload — same as audit event's "after" field
    "id": "inc_01HX...",
    "number": "INC-1042",
    "title": "API Gateway returning 503 errors",
    "severity": "P1",
    "status": "open",
    // ...
  }
}

HMAC Signature Verification

When a secret is configured, every delivery includes:

http

X-FlowOS-Signature-256: sha256=<hmac_hex>
X-FlowOS-Delivery:      evt_01HX...
X-FlowOS-Event:         incident.created

Verify the signature in your endpoint:

typescript

import { createHmac } from 'crypto'

function verifySignature(body: string, signature: string, secret: string): boolean {
  const expected = 'sha256=' + createHmac('sha256', secret).update(body).digest('hex')
  return expected === signature
}

app.post('/flowos-webhook', (req, res) => {
  const sig = req.headers['x-flowos-signature-256'] as string
  if (!verifySignature(req.rawBody, sig, process.env.WEBHOOK_SECRET!)) {
    return res.status(401).send('Invalid signature')
  }
  // process event...
  res.status(200).send('ok')
})

Payload Filtering

Avoid delivering events you don't care about. Filters use the same condition syntax as workflow triggers:

json

// Only deliver P1 incident events
{
  "filter": {
    "data.severity": "P1"
  }
}

// Only deliver resolved or closed incident updates
{
  "filter": {
    "data.status": { "in": ["resolved", "closed"] }
  }
}

Delivery Log

Every delivery attempt is logged. View the log on the webhook detail page or via API:

GET

/api/v1/webhooks/:id/deliveries

List delivery attempts for a webhook.

GET

/api/v1/webhooks/:id/deliveries/:deliveryId

Get a single delivery with request/response details.

POST

/api/v1/webhooks/:id/deliveries/:deliveryId/retry

Manually retry a failed delivery.

Auto-Pause on Failure

If a webhook endpoint fails to respond with 2xx across all retry attempts for 5 consecutive deliveries, the webhook is automatically paused and a notification is sent to workspace admins. Re-enable it once the endpoint is fixed.

Testing Webhooks

bash

# Send a test ping to verify endpoint reachability
POST /api/v1/webhooks/:id/test

# Response includes the endpoint's HTTP status and response body
{ "status": 200, "latency_ms": 142, "body": "ok" }