Choose events
The catalog contains nine event types:ticket.created,ticket.updated, andticket.resolveddescribe ticket state changes.approval.requestedidentifies an approval request and its eligible approver principal IDs.workflow_run.startedmeans the automation acknowledged execution immediately before its body begins.workflow_run.waiting_for_approvalidentifies an approval that blocks execution.workflow_run.completed,workflow_run.failed, andworkflow_run.canceleddescribe terminal outcomes.
wait_reason_kind: "pre_admission_approval". An approval during execution uses wait_reason_kind: "approval". A run can wait for startup approval or fail dispatch before it starts. Those runs have no started event.
Run events describe production runs of published automations. Test runs and system executions do not produce these public lifecycle events. A cancellation request becomes a canceled event when Flow acknowledges terminal cancellation.
Read an event
Deliveries use CloudEvents 1.0 withContent-Type: application/cloudevents+json. The corrected payload contract uses data.event_schema_version: 2. Event schema versions are independent of REST API path versions.
time, data.occurred_at, and payload lifecycle timestamps use RFC 3339 in Coordinated Universal Time (UTC), with milliseconds. For example: 2026-10-03T02:21:32.164Z.
The envelope includes the event ID, organization and team IDs, source identity and revision, and ticket linkage when applicable. Available correlation metadata uses flowcorrelationid, flowrequestid, and flowcausationid. Flow omits dataschema until a public schema URL exists.
Payloads contain compact state and linkage fields. Approval payloads contain principal IDs and applicable approval, source, ticket, access request, run, and step IDs. They exclude email addresses, delivery routes, actor snapshots, and ticket content. Run payloads exclude complete inputs, outputs, and error summaries. Retrieve the run resource when you need execution details and have access.
Add a callback
The existing automation-start request accepts optionaldata.callback_webhook_endpoint_id. Omit it or use null when you do not need a callback. A team manager can select an enabled endpoint in the run’s team. An organization owner or administrator can select an enabled organization endpoint or an endpoint in the run’s team.
An endpoint in another team is ineligible, even when you administer both teams or the organization. Organization-published automations use the resolved execution team for this check. Permission to start an automation does not grant permission to select callbacks. Selection does not require permission to list organization endpoints.
Callbacks receive actual start, both approval waits, completion, failure, and cancellation, including a failure before execution. A callback does not need subscriptions. When a subscription also matches, Flow creates one delivery for that endpoint and event.
Service-account callers cannot select callbacks, including accounts with automation invocation grants or administrative roles. Unknown, foreign-organization, unauthorized, or incompatible-team endpoints return 404 webhook_endpoint_not_found. An accessible endpoint with compatible scope that is disabled returns 409 webhook_endpoint_disabled. A malformed identifier returns 400 invalid_request_body. Service-account selection returns 400 callback_endpoint_not_granted. Changing callback selection when you reuse an idempotency key returns an idempotency conflict.
Verify and acknowledge a delivery
Read the raw request bytes before parsing JSON. Compute a hash-based message authentication code (HMAC) with SHA-256 over the UTF-8 bytes oftimestamp + "." + raw_body, using your signing secret.
Flow-Webhook-Timestampcontains Unix epoch seconds.Flow-Webhook-Signaturecontainsv1=<hex_digest>.Flow-Webhook-Delivery-Ididentifies the delivery.
2xx response after accepting the event.
Delivery is at least once. Deduplicate repeated attempts by delivery ID. A retry preserves the exact body and delivery ID, with a new attempt timestamp and signature. A replay preserves the event ID and exact body but receives a new delivery ID. Deduplicate by event ID when replay must not repeat your business action.
Replay checks the delivery, source event, and endpoint scope before creating a new delivery. An incompatible historical delivery returns 404 webhook_delivery_not_found and creates no replay or delivery job. Disabling an endpoint prevents new delivery planning and dispatch.
Test sends use a schema-valid synthetic payload for the selected event type and include data.test: true. Handle the test marker before taking business actions.
Update an endpoint
An endpoint update accepts onlydisplay_name, url, event_types, and status. Unsupported or immutable fields, empty updates, and malformed values return 400 invalid_request_body with field violations. Flow rejects the entire request when any field is invalid. A normalized update that changes nothing preserves updated_at.
Creation distinguishes an omitted team from an explicit null. Omitted scope inherits your selected routing team. An explicit null selects organization scope and requires organization owner or admin access. An explicit team ID selects that authorized team and takes precedence over the routing header. You cannot transfer an endpoint between teams.
Migrate existing receivers
Version 2 changes started-event timing, approval disclosure, timestamp formatting, and correlation extensions. Verify your receiver before activation. Captured version 1 deliveries retain their original body during the seven-day drain window. After activation, replay of version 1 returns409 webhook_contract_retired. At the deadline, Flow exhausts remaining version 1 deliveries.