Cloudflare has added a streaming interface for Workflow instances, allowing a Worker or any HTTP client to pull the full event log and then stay attached for new events using WorkflowInstance.subscribe() or the GET /subscribe endpoint. Real‑time consumption replaces the traditional poll‑for‑status pattern and opens the door to immediate UI updates, alerting, or downstream orchestration.
How the Subscription Works
When a subscription is opened, the service first emits every recorded event for the requested instance, guaranteeing that the consumer sees the complete history. After the backlog is drained, the connection remains open and yields new events as they occur. Optional parameters let you narrow the feed: filter restricts the stream to specific event types, and cursor can start the stream at a particular event offset, which is useful for resuming after a disconnect.
Practical Use Cases
- Live dashboards: Feed the stream into a UI component to reflect step completions, retries, or rollbacks without a separate status‑polling loop.
- Automated notifications: Trigger a webhook or send a message when a step reaches a terminal state, using the event type as the trigger condition.
- Chained workflows: Launch follow‑up work in another Worker as soon as a specific event, such as a
sleepcompletion, is observed.
Implementation Considerations
The JavaScript example below shows the pattern: acquire the instance, call subscribe(), then iterate with next() until the iterator reports done. Because the iterator is asynchronous, the loop does not block the Worker’s event loop, but you should still respect the Worker’s execution time limits and clean up the subscription when finished.
const instance = await env.MY_WORKFLOW.get("report-123");
using subscription = await instance.subscribe();
while (true) {
const { value, done } = await subscription.next();
if (done) break;
console.log(value.type, value);
}
When using the HTTP endpoint, the same semantics apply: the response is a stream of JSON objects that can be parsed incrementally. Keep in mind that network interruptions will terminate the stream; you can restart with a saved cursor to avoid missing events.
Related CloudNinjas coverage: hands-on guides.
What This Means For Practitioners
Adopt the streaming API to eliminate polling loops and reduce latency in monitoring and automation pipelines. Evaluate the event volume you need—using filter can lower bandwidth and processing overhead. Ensure that only authorized Workers or services can invoke the subscription endpoint, as the stream reveals internal workflow state. Finally, instrument your Workers to handle graceful shutdowns and reconnections, preserving the cursor when a stream is interrupted.
