Skip to main content
When an agent needs to confirm that a webhook arrived — after deploying a fix, or while validating an integration — wait for it directly. expect and tail use the live observe stream and return when the condition is met, which is cheaper and more reliable than polling events search in a loop.
Both commands are envelope exceptions: they always emit JSON (even without --json) and do not use the {schema, data} wrapper. expect returns one bare object; tail emits NDJSON.

​
Wait for one match

Use expect to block until a single matching webhook arrives.
On a match it prints a bare object and exits 0:
expect exits 0 on a match and 7 (timeout) if nothing matches before --timeout (default 30s). Branch on the exit code, then read the object for the matched event_id.
The observe stream has no backfill. Open expect before you trigger the action you’re waiting on — a stream you open afterward will never replay the event you missed. See Consistency model.

​
Stream a bounded set

Use tail to capture several live events as NDJSON — one object per line.
--count stops after N events (0 = unlimited); --max-wait stops at a deadline (0 = no limit), both exiting 0. Set at least one bound so an agent never streams forever, and parse line by line — don’t wait for a closing array. The filter fields are the live-stream subset documented in Search & filters.

​
Why not poll

Polling burns rate limit and adds latency. When no wait command fits, poll deliberately — exponential backoff and a deadline, detailed in Caching & performance.

​
Continue

Diagnose a webhook

Once an event arrives, inspect it and its delivery chain.

Consistency model

Why the stream has no backfill, and which plane answers which question.

Caching & performance

When polling is unavoidable, do it intentionally.