> ## Documentation Index
> Fetch the complete documentation index at: https://smithers.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# <WaitForEvent>

> Durably suspend until a correlated external event arrives, or time out.

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { WaitForEvent } from "smithers-orchestrator";

type WaitForEventProps = {
  id: string;
  event: string;
  output: z.ZodObject | Table | string;
  correlationId?: string;
  outputSchema?: z.ZodObject;
  timeoutMs?: number;
  onTimeout?: "fail" | "skip" | "continue"; // default "fail"
  async?: boolean; // unrelated downstream may proceed while pending
  skipIf?: boolean;
  dependsOn?: string[];
  needs?: Record<string, string>;
  label?: string;
  meta?: Record<string, unknown>;
  key?: string;
};
```

```tsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
<Workflow name="deploy-watcher">
  <Sequence>
    <WaitForEvent
      id="wait-deploy"
      event="deploy.completed"
      correlationId={ctx.input.deployId}
      output={outputs.deployEvent}
      outputSchema={deployPayload}
      timeoutMs={600_000}
      onTimeout="fail"
    />
    <Task id="notify" output={outputs.summary} agent={notifier}>
      The deploy finished. Summarize the result.
    </Task>
  </Sequence>
</Workflow>
```

## Notes

* Push-based; for poll-based checks use `<Task>` with a compute function.
* External integration webhooks (the `@smithers-orchestrator/integrations` package) deliver these events. A source signals `integration:<service>:<event>` (for example `integration:github:pull_request`) with a `correlationId` that is `owner/repo#number`, `owner/repo`, or `null` depending on the payload, so set `signalName` and `correlationId` to match.
* With `async`, dependents via `dependsOn`/`needs` still block until payload arrives.
* Async waits are tracked by the `smithers_external_wait_async_pending{kind="event"}` gauge while pending (it rises on start, falls on completion).
* A run suspended on `<WaitForEvent>` (status `waiting-event`) does not resume itself when the event is delivered out of process. A controller should deliver it with Gateway `submitSignal`, then call `resumeRun`. For ad-hoc CLI operation, deliver the event and resume with `bunx smithers-orchestrator up workflow.tsx --run-id RUN_ID --resume true` from the workspace root. Never locate or select the backing store yourself; discover the verified workspace Gateway with `smithers gateway status --format json`. See the keeper-loop pattern in the [CLI overview](/cli/overview).