RespondingHook — hooks that can reply to their caller

[pranaygp]

Summary

This RFC proposes createRespondingHook(): a Hook that can send a value back to whoever resumed it.

The capability already exists in the SDK, but only inside createWebhook({ respondWith: 'manual' }), where it is welded to HTTP semantics and a public URL. This RFC lifts it out into its own primitive, so any resumer — an authenticated route, a Slack event handler, a queue consumer, an MCP tool — can get an answer back from a running workflow. createWebhook() then becomes what it should have been all along: a responding hook specialized to Request/Response, on a URL we generate for you.

// workflow
using hook = createRespondingHook<Query, Quote>();
for await (const msg of hook) {
  await reply(msg); // a step that calls msg.respond(...)
}

// anywhere that can resume a hook
const quote = await resumeRespondingHook<Query, Quote>(token, { sku: 'ABC' });

Scope. This is a repackaging of the mechanism webhooks already use, exposed for userland consumption. It is not a new World-level capability: no changes to any World, to workflow-server, or to how anything is stored. The generality was recognized when webhooks were added; webhook deliberately kept the narrower single-Response shape for simplicity, and this RFC is about making the general shape available on its own.

Motivation

Hook is one-way: something outside pushes a value in, and the resumer learns nothing except that the write landed. resumeHook() returns the hook entity.

Webhooks are not one-way. createWebhook({ respondWith: 'manual' }) lets a step call request.respondWith(response), and the caller's HTTP request stays open until that response arrives. Underneath, the resumer mints a stream, hides its writable in the payload, and reads a value back off it. That machinery is entirely generic — nothing about it needs Request or Response or a URL.

Today, wanting a reply forces you to accept three things you may not want:

1. A public, unauthenticated endpoint. createWebhook() sets isWebhook: true, which makes the hook resumable at /.well-known/workflow/v1/webhook/:token by anyone holding the token. The docs already tell you to prefer createHook() behind your own authenticated route — but doing so gives up the ability to reply.
2. HTTP types. Your reply must be a Response, and your message must be a Request, even when neither side of the interaction is HTTP.
3. A generated token. createWebhook() throws if you pass one, so the deterministic-token patterns that createHook() supports (order:${orderId}) are off the table.

You can call resumeWebhook(token, request) from your own route, but the hook is still publicly resumable, you still have to construct a Request and unwrap a Response, and you still can't choose the token.

The gap is that "can reply" is currently inseparable from "exposed over public HTTP." Those are two different decisions and users should get to make them independently.

Proposed API

Workflow side

import { createRespondingHook, type HookMessage } from 'workflow';

async function reply(msg: HookMessage<Query, Quote>) {
  'use step';
  await msg.respond(priceFor(msg.data));
}

export async function quoting() {
  'use workflow';

  using hook = createRespondingHook<Query, Quote>({ token: `quotes:${sessionId}` });

  for await (const msg of hook) {
    await reply(msg);
  }
}

createRespondingHook<TMessage, TResponse>(options?) returns a RespondingHook<TMessage, TResponse>, which is a Hook in every respect — thenable, async-iterable, getConflict(), dispose(), using — except that it yields HookMessage envelopes instead of bare payloads.

interface HookMessage<TMessage, TResponse> {
  /** The payload the resumer sent. */
  readonly data: TMessage;

  /** Send the reply. Step context only. */
  respond(value: TResponse): Promise<void>;
}

The envelope is necessary rather than aesthetic: a hook payload can be a string or a number, and there is nowhere to hang a respond method on a primitive. .data is always where the payload lives, regardless of its type.

respond() takes any serializable value, which is the same set of things a step can return — including a ReadableStream. There is no separate streaming API, and there shouldn't be: streams already serialize across every other boundary in the SDK, so a streaming reply is just a reply whose value happens to be a stream. This is the one capability the webhook version doesn't expose today, because a webhook's single chunk is always a Response (whose body is the only stream it can carry).

Resumer side

import { resumeRespondingHook } from 'workflow/api';

const quote = await resumeRespondingHook<Query, Quote>(token, { sku: 'ABC' });

It returns whatever the workflow responded with. If that's a stream, you get a stream:

const tokens = await resumeRespondingHook<Query, ReadableStream<Token>>(token, { sku: 'ABC' });
for await (const t of tokens) process.stdout.write(t);

Options

interface RespondingHookOptions {
  token?: string;                      // deterministic tokens allowed, unlike createWebhook()
  metadata?: Serializable;
  experimental_minRetention?: StringValue | Date | number;
}

interface ResumeRespondingHookOptions {
  signal?: AbortSignal;
  timeout?: StringValue | number;      // reject if no reply arrives in time
}

Notably absent: isWebhook. A responding hook is not publicly resumable unless you also make it a webhook. That is the whole point.

Typed variant

Both sides need the same two type parameters, so the defineHook() pattern carries over:

// shared module
export const quotes = defineRespondingHook<Query, Quote>();

// workflow
using hook = quotes.create();

// route
const quote = await quotes.resume(token, { sku });

The ladder

The three primitives become strictly layered, each one a specialization of the previous:

	Direction	Payload	Addressing
Hook	in	anything serializable	your route, your auth
RespondingHook	in and out	anything serializable	your route, your auth
Webhook	in and out	Request / Response	generated public URL

Stated as code, createWebhook() collapses to:

createWebhook()           = createRespondingHook<Request, Response>({ isWebhook: true })
resumeWebhook(token, req) = resumeRespondingHook(token, req) + 202/static-Response defaults
request.respondWith(res)  = msg.respond(res)

Rebuilding createWebhook() on the new primitive is part of the proposal, not a follow-up — an abstraction nothing is built on isn't an abstraction. This is a pure refactor: no change to the public webhook API, no change to the bytes stored on the hook, no change to the .well-known route.

Example use cases

Human-in-the-loop approval that answers the approver

Today the approver's request returns 202 and the UI polls to find out what happened. With a responding hook the decision comes back on the same call:

// workflow
using approvals = createRespondingHook<Decision, ApprovalResult>({
  token: `approval:${orderId}`,
});

const msg = await approvals;
if (msg.data.approved) {
  const shipment = await ship(order);
  await respond(msg, { status: 'shipped', trackingId: shipment.id });
} else {
  await respond(msg, { status: 'rejected' });
}

// your authenticated route — not a public webhook
export async function POST(req: Request) {
  const { orderId, approved } = await requireAdmin(req);
  const result = await resumeRespondingHook(`approval:${orderId}`, { approved });
  return Response.json(result);
}

Streaming a reply into a chat UI

An agent workflow that stays alive across a conversation. Each user message is a resume; the assistant's tokens stream back to that specific caller, not to the run's output stream:

// workflow
using chat = createRespondingHook<UserMessage, ReadableStream<UIMessageChunk>>({
  token: `chat:${conversationId}`,
});

for await (const msg of chat) {
  await answer(msg, history);
}

// step — the reply is a stream, so `respond()` takes a stream
async function answer(
  msg: HookMessage<UserMessage, ReadableStream<UIMessageChunk>>,
  history: Message[]
) {
  'use step';
  const result = streamText({ model, messages: [...history, msg.data] });
  await msg.respond(result.toUIMessageStream());
}

// route
export async function POST(req: Request) {
  const { conversationId, text } = await req.json();
  const stream = await resumeRespondingHook(`chat:${conversationId}`, { text });
  return new Response(stream);
}

This is the case getWritable() cannot serve: getWritable() writes to the run's stream, which every reader of the run sees. A responding hook gives you a reply channel scoped to one resume call, which is what a request/reply chat turn actually is.

Validate at the door

The workflow inspects the payload and tells the caller immediately whether it was accepted, instead of accepting everything and failing invisibly later:

for await (const msg of intake) {
  const problems = validate(msg.data);
  if (problems.length) {
    await respond(msg, { accepted: false, problems });
    continue;
  }
  await respond(msg, { accepted: true, id: await enqueue(msg.data) });
  break;
}

Non-HTTP transports

Slack Events, Discord interactions, an MCP tool handler, a gRPC service, a Kafka consumer that must ack with a result. All of them are request/reply, none of them want a public .well-known URL or a Response object. Today each one has to fake HTTP through createWebhook; with this they use the primitive directly.

Reading live state out of a run

Not the primary use case, but it falls out for free: a hook whose message is a query and whose reply is derived from the workflow's in-memory state.

Semantics

Question	Answer
Who creates the reply channel?	The resumer, once per resume call. Concurrent resumes of the same hook each get their own channel and never cross.
How many replies per message?	Exactly one respond() call. A second one throws. Send many values by responding with a stream.
Where can respond() be called?	Inside a "use step" function only, same as request.respondWith() today.
What can a reply be?	Anything a step can return, streams included.
What if the workflow never replies?	The caller rejects with HookResponseNotSentError once the run ends, or on timeout / signal.
What if the caller stops listening?	Writes are discarded and the workflow is not notified — the same posture as an HTTP client disconnecting mid-response.
What happens on step retry?	The reply is re-sent from the top of the retried step, following the same rules as a step that returns a value or a stream.
Where does the reply live?	The run's stream storage, keyed per resume. It is not in the event log and not the run's return value.
Can a plain createHook() reply?	No. resumeRespondingHook() on a non-responding hook throws.
Is it publicly resumable?	No, unless it is also a webhook.

The one that most deserves to be stated plainly in the docs rather than discovered: respond() is step-only, exactly as respondWith() is today.

Naming

Prior art for the one-way vs. request-reply distinction is unusually consistent:

System	One-way	Request/reply
Temporal	Signal	Update (and Query, for reads)
Erlang/OTP gen_server	cast	call
Akka	tell	ask
Orleans / Azure Durable Entities	signal	call
Restate	send	call / request

Alternatives considered:

• QueryHook — Temporal's vocabulary, so people (and models) arriving from Temporal recognize the concept immediately and can read up on the nuances. Against: Temporal's Query is specifically a read-only, non-blocking view of workflow state; this is neither, so the word imports a contract we don't honor.
• UpdateHook — semantically the closer Temporal analogue (Update takes input, may mutate, returns a result). Against: "update" reads as modify a thing at the call site and says nothing about getting an answer back — resumeUpdateHook(token, payload) doesn't describe what happens.
• RequestHook — gives the tightest one-liner ("a Webhook is a RequestHook over HTTP"), but overloads Request in a codebase where Request already means the DOM class, in exactly the API where both appear together.
• CallableHook / callHook — strongest industry precedent, but call is close to meaningless in JS, and createCallableHook reads worse than the prior art suggests it would.
• DuplexHook, Exchange, AskHook — respectively jargon, and two that break the Hook lineage that makes the concept easy to teach.
• An option on createHook() (createHook({ respond: true })) — smallest surface, but it makes Hook<T> vs Hook<TMessage, TResponse> a discriminated mess in the types, and it gives the concept nowhere to live in the docs. It stays a hidden mode rather than the middle rung people learn between hooks and webhooks.

There is a general argument against borrowing from Temporal here: Query and Update are heavy concepts in Temporal, each with their own lifecycle, validators, and delivery guarantees. Naming after them makes this look like a third top-level thing to learn. It isn't. RespondingHook reads as a variant of Hook, which is exactly what it is, and it keeps Request/Response free to mean what they already mean.

The resumer-side name is the weakest link. resumeRespondingHook() is chosen for symmetry with createHook/resumeHook and createWebhook/resumeWebhook, and it is unambiguous at the call site, but it is long and not pretty. See open questions.

Docs

The concept slots directly after Hooks and before Webhooks, which is also the dependency order: a new foundations/responding-hooks page between hooks and streaming, with the webhook section of the hooks page gaining a line saying it is this primitive specialized to HTTP. Nothing about hooks needs to be learned differently, and nothing about webhooks changes.

Non-goals

• No new Hook entity field, no World or workflow-server change. The "this hook replies" flag rides in hook metadata, exactly as respondWith does today.
• No new streaming API. A streaming reply is a reply whose value is a stream.
• No change to createWebhook()'s public API, stored bytes, or route.
• No cross-version break. The public webhook route is served by current production while a hook may belong to a run on an older deployment, so both the old and new metadata shapes stay readable in both directions.
• Not a replacement for getWritable(). That writes to the run's stream, visible to every reader of the run. This writes to one caller.
• Not a durable record. A reply is a response, not an event. If you need it in the log, write it there.

Open questions

1. Naming, both halves. RespondingHook is proposed above; QueryHook and UpdateHook are the live alternatives, weighed in the naming section. The resumer-side verb is more open than the type name: resumeRespondingHook(), askHook(), requestHook(), resumeHookWithResponse(), or an options-driven overload of resumeHook() that changes its return type.
2. Should respond() work from workflow context? It is step-only today for a mechanical reason (the real stream only materializes in the step environment), and the existing docs already say "this requirement may be removed in the future." There is a plausible path via an SDK-owned hoisted step, like workflow's fetch. Worth doing now, or later?
3. defineRespondingHook() or extend defineHook()? A second define* is more discoverable; extending the existing one is less API.
4. Should replies be readable after the fact? They land in stream storage but are not in the event log, so observability shows nothing today. Is a reply worth surfacing in the run timeline, or is it correctly invisible?
5. Should a caller be able to opt out of the reply channel (fire-and-forget against a responding hook), and if so, does respond() throw or no-op?
6. Cost. Discovering that a hook replies requires hydrating its metadata, which costs a run-key round trip on resume — the same one respondWith: 'manual' webhooks pay today. Acceptable, or worth a first-class field on the hook entity in a follow-up?

[msullivan]

Some thoughts about what the python version might look like:

In python workflow, hooks are defined by subclassing BaseHook, so we'd add a BaseRespondingHook

class RespondingHook[TResponse](Hook):
    response: TResponse

class BaseRespondingHook[TResponse](BaseHook):
    async def respond(self, value: TResponse) -> None:
        ...

    # returns a context manager that gives back something with a .write() method
    async def respond_stream(self) -> _HookStreamWriter[TResponse]:
        ...

and then using it looks like:

class Response(pydantic.BaseModel):
    ...

class Query(BaseHook[Response], pydantic.BaseModel):
    ...

@wf.step
async def reply(hook: Query, response: Response) -> None:
    await hook.respond(response)

@wf.workflow
async def wf() -> None:
    async for query in Query.wait(token=...):
        response = ...
        await reply(query, response)