> ## Documentation Index > Fetch the complete documentation index at: https://docs.letsflow.ai/llms.txt > Use this file to discover all available pages before exploring further. # Receive automation webhooks > Verify event signatures, follow automation progress, and handle retries. Flow sends webhooks to the enabled endpoints you configure in administration. You can subscribe to ticket, approval, and automation run events. ## Choose events The catalog contains nine event types: * `ticket.created`, `ticket.updated`, and `ticket.resolved` describe ticket state changes. * `approval.requested` identifies an approval request and its eligible approver principal IDs. * `workflow_run.started` means the automation acknowledged execution immediately before its body begins. * `workflow_run.waiting_for_approval` identifies an approval that blocks execution. * `workflow_run.completed`, `workflow_run.failed`, and `workflow_run.canceled` describe terminal outcomes. A startup approval uses `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 with `Content-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 optional `data.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 of `timestamp + "." + raw_body`, using your signing secret. * `Flow-Webhook-Timestamp` contains Unix epoch seconds. * `Flow-Webhook-Signature` contains `v1=`. * `Flow-Webhook-Delivery-Id` identifies the delivery. Compare signatures in constant time. Reject timestamps outside your replay window, for example five minutes. Return a `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 only `display_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 returns `409 webhook_contract_retired`. At the deadline, Flow exhausts remaining version 1 deliveries. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.