# Flow Webhooks

Flow supports per-run callback URLs on run creation and team-level webhook subscriptions managed through the public v2 API. Team subscriptions are API-only; there is no web settings tab.

## Event Catalog

- `run.started`
- `run.paused`
- `run.completed`
- `run.failed`
- `run.message.created`
- `run.tool_call.completed`
- `run.file.created`
- `human_request.created`
- `human_request.responded`
- `queue.case.created`
- `queue.case.claimed`
- `queue.case.completed`
- `assignment.build.published`
- `connection.updated`
- `connection.action_required`

## Payload Envelope

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "run.completed",
  "created_at": "2026-07-18T12:00:00.000Z",
  "data": {
    "run_id": "550e8400-e29b-41d4-a716-446655440001",
    "status": "completed"
  }
}
```

Use `id` as the delivery and event deduplication key. Transient non-2xx delivery failures are retried through Flow's durable outbox with backoff and eventual dead-lettering.

## Signatures

Signed deliveries include:

- `X-Flow-Signature: t=<unix seconds>,v1=<hex hmac-sha256(secret, "<t>.<rawBody>")>`
- `X-Flow-Event: <event name>`
- `X-Flow-Delivery: <delivery uuid>`

Verify against the raw request body, reject stale timestamps, and compare HMAC values with a timing-safe comparison. Rotate the workspace webhook secret when ownership or integration scope changes.

## Management API

- `GET /v2/teams/{teamId}/webhooks`
- `POST /v2/teams/{teamId}/webhooks` with `url` and `events[]`
- `DELETE /v2/teams/{teamId}/webhooks/{subscriptionId}`
- `GET /v2/teams/{teamId}/webhook-secret`
- `POST /v2/teams/{teamId}/webhook-secret/rotate`

Webhook URLs must be public HTTP(S) URLs and pass Flow's SSRF guard.