Waiting for Events
A run can pause until something outside it happens, such as a manager approving an expense, a payment provider calling a webhook, or a customer replying, and continue with the data that event carries. While it waits, the run is a row in the table; no worker or connection is held open, however long the wait.
Wait for an event
Return wait_for from a step, naming the step the event should run:
from datetime import timedelta
from typing import Literal
from reflex_workflow import Workflow, step, wait_for
class Expense(Base, Workflow):
__tablename__ = "expense"
id: Mapped[int] = mapped_column(primary_key=True)
amount: Mapped[int]
status: Mapped[str] = mapped_column(String(32), default="draft")
decided_by: Mapped[str | None] = mapped_column(String(255), default=None)
@step
async def request_approval(self):
await notify_manager(self.id)
self.status = "pending"
return wait_for(
Expense.decide,
timeout=timedelta(days=2),
on_timeout=Expense.escalate,
)
@step
async def decide(self, verdict: Literal["approve", "reject"], *, by: str):
self.status = "approved" if verdict == "approve" else "rejected"
self.decided_by = by
@step
async def escalate(self):
await notify_finance(self.id)
self.status = "escalated"ExpandCollapse
The step you wait on is the channel: an event addressed to Expense.decide ends this wait and runs decide with the event's arguments.
timeout and on_timeout are optional, and go together. With them, the run gives up waiting once the timeout passes and runs on_timeout instead. Without them, it waits indefinitely.
Deliver an event
To deliver an event, address the runs it is for and call deliver with the step and its arguments:
class ApprovalState(rx.State):
manager_email: str = ""
@rx.event
async def approve(self, expense_id: int, request_id: str):
accepted = await Expense.by(Expense.id == expense_id).deliver(
Expense.decide("approve", by=self.manager_email),
key=request_id,
)
if not accepted:
return rx.toast("This expense is no longer waiting for approval.")deliver returns how many runs accepted the event. A run accepts an event when it is waiting for that step, or when it hasn't reached its wait yet; see Events that arrive early. A run that is waiting for a different step, or has finished, refuses it.
The arguments are checked against the step's signature before anything is written, so a payload that doesn't fit the step raises instead of failing later in the run.
Deliver each event once
Webhooks are retried and users double-click. Pass a key that identifies the event, such as the webhook's delivery ID, and a run accepts each key only once. This webhook is a route on a FastAPI app passed to Reflex as an API transformer:
from fastapi import HTTPException
@fastapi_app.post("/webhooks/payments")
async def payment_webhook(event: PaymentEvent):
invoice = Invoice.by(Invoice.payment_id == event.payment_id)
if await invoice.deliver(Invoice.paid(event.amount), key=event.id):
return {"ok": True}
run = await invoice.get()
if run is not None and event.id in (run.recent_event_keys or []):
# Accepted by an earlier delivery.
return {"ok": True}
# Not taken: ask the sender to retry.
raise HTTPException(status_code=503)A run remembers the last 16 keys it has accepted, and deliver returns 0 for a repeat. Without a key, every delivery counts as a new event.
A return value of 0 doesn't tell you why no run took the event: the run may not exist yet, may already have the event, may be holding a different one, or may have stopped waiting. The webhook above acknowledges an event only when it knows a run took it, now or on an earlier delivery, and otherwise returns an error so the sender retries. A run created between the two calls is safe, because the error makes the sender deliver again. The cost is that an event no run will ever take is retried until the sender gives up.
Events that arrive early
An event can arrive before the run starts waiting for it. For example, a payment webhook can arrive while the step that requested the payment is still running. The run holds the event, and applies it as soon as it waits for that step, so a fast reply is never lost.
A held event is discarded if the run instead goes on to wait for a different step, finishes, or moves to its next scheduled occurrence. In that case, whoever sent the event has to send it again. The key of a discarded event isn't remembered, so the resend is accepted.
A run holds at most one event. While it holds one that no worker has taken yet, deliver refuses a second event and returns 0, rather than replacing an answer that was already given. Once a worker takes the held event to run its step, the run can hold the next one, for the wait that step sets up. A run that waits on the same step again, such as a chat that waits for each message in turn, doesn't miss a message that arrives while it handles the previous one.
Deadlines
The deadline decides when a wait ends. Once it passes, the run refuses events and deliver returns 0, even if no worker has run the timeout step yet. A sender that keeps retrying can't extend a deadline by racing the workers.
The deadline is compared with the time the delivery's database statement starts. A delivery that starts just before the deadline and then waits for a lock held by another transaction is accepted, even if it commits just after the deadline.
Restart finished runs with an event
A finished run refuses events. For a run that should live as long as its events keep coming, such as a support conversation that closes after a quiet period, pass restart=True:
await Conversation.by(Conversation.thread_id == thread_id).deliver(
Conversation.reply(message.text),
key=message.id,
restart=True,
)A waiting run takes the event as usual. A finished run starts again at the event's step, with the event's arguments.