Cascades Docs
Sign in to run requests with your own sandbox key. Sign in
View as Markdown Open in Claude Open in ChatGPT Add MCP server OpenAPI JSON OpenAPI YAML

execution.failed

An execution reached `failed`

Sent once when an execution's status transitions to failed. first_error_message is the engine's first recorded error; the full failed_steps array is available from GET /executions/{workflow_execution_id} with executions:read:full.

Payload

  • id string (uuid) required
  • event string required One of execution.failed
  • created_at string (date-time) required
  • data object required
    • workflow_execution_id integer required
    • workflow_id integer required
    • batch_execution_id integer Present only for batch rows.
    • external_reference string
    • execution_mode string One of test live
    • status string required One of failed
    • review_status string required One of none in_review approved denied
    • completed_at string (date-time)
    • first_error_message string The first error the engine recorded for this run.

How to handle it

  1. Answer 2xx as soon as the delivery is stored and do the real work on a queue. Any other response, a connection error or a timeout (5 s connect, 10 s read) counts as a failure: Cascades retries after 1m, 5m, 30m, 2h, 8h, 24h, then marks the delivery dead.
  2. De-duplicate on the envelope's id — it is identical across retries and across every subscriber's copy of the same event — or on the X-Cascades-Delivery header, which names one delivery row.
  3. Verify X-Cascades-Signature before you act on the body (next section).
  4. Treat data as a pointer, not the record: read data.workflow_execution_id and call GET /executions/{id} for the current status, the decision and — with executions:read:full — the step_outputs.
  5. data.execution_mode says whether the run was test or live. Test-mode runs deliver this event too, so guard production side effects on it.

Verify before you trust it

Compute HMAC-SHA256(signing_secret, "<t>.<raw body>") and compare it in constant time with the v1 (or, during rotation, v0) value in X-Cascades-Signature. Samples are in the right-hand rail and in the verify webhooks guide.

Deliveries retry on any non-2xx response, so handle the same X-Cascades-Delivery id more than once safely. See all webhook events.

Was this page helpful?