Lifecycle Hooks

Lifecycle hooks observe durable workflow and step outcomes without changing the business result.

Workflow hooks

on-start, on-success, on-error, on-cancel, and on-complete observe the run. on-complete runs last for every terminal outcome.

Step hooks

on-step-start, on-step-success, on-step-failure, and on-step-complete can filter step IDs with the steps attribute.

<lifecycle>
  <on-error><script>console.error(lifecycle.failure.message);</script></on-error>
  <on-complete><notify><telegram chats="123" message="Run completed" bot-token="{{secrets.TELEGRAM_BOT_TOKEN}}" /></notify></on-complete>
</lifecycle>

Hook source order does not define execution order. Returned values do not enter context.steps, and hook failures become warnings rather than replacing the workflow outcome.

Use lifecycle for observation

<lifecycle>
  <on-start>
    <script>
      console.log("Order workflow started");
    </script>
  </on-start>

  <on-step-failure steps="chargePayment reserveStock">
    <script>
      console.error(
        `Step ${lifecycle.step.id} failed after ${lifecycle.step.attempts} attempts`
      );
    </script>
  </on-step-failure>

  <on-error>
    <notify>
      <telegram
        chats="123456789"
        message="Order workflow failed"
        bot-token="{{secrets.TELEGRAM_BOT_TOKEN}}"
      />
    </notify>
  </on-error>

  <on-complete>
    <script>console.log("Order workflow finalized");</script>
  </on-complete>
</lifecycle>

Step filters are whitespace-separated IDs. Omit steps to observe every executable step, including nested ones.

Understand lifecycle data

Lifecycle scripts receive normal bindings plus lifecycle.event, workflow identity and outcome, optional step identity and outcome, attempt count, and safe failure information.

Hooks cannot create context.steps values, select a route, retry a step, or rewrite the workflow result. Anything required for business correctness belongs in ordinary steps.

Hook failure becomes a warning so observability does not silently replace the business outcome. Final lifecycle state distinguishes clean completion from completion with warnings.

Reusable definitions support only on-success, on-error, and on-complete, and their hooks are script-only observers.