context.waitForWebhook - Upstash Documentation

context.waitForWebhook() pauses workflow execution until the webhook created by createWebhook is called or a timeout is reached.

You can call context.waitForWebhook with the same webhook object multiple times to wait for multiple calls to the same webhook URL.

Arguments#

stepNamestringrequired#

Name of the step.

webhookobjectrequired#

The webhook object returned by context.createWebhook().

Show properties

webhookUrlstring#

The webhook URL to wait for.

eventIdstring#

The internal event identifier.

timeoutstringrequired#

The maximum time to wait before continuing execution.

Should be passed in Human‑readable duration (e.g., "10s", "2h", "1d").

Response#

The response varies depending on whether the webhook was called before the timeout:

timeoutboolean#

false if the webhook was called successfully
true if execution resumed because the timeout elapsed

requestRequest | undefined#

The HTTP request object received by the webhook (only present when timeout is false).

Contains the full request details including method, headers, body, and URL.

Usage#

Basic Example#

import { serve } from "@upstash/workflow/nextjs";export const { POST } = serve(async (context) => {  // Create webhook  const webhook = await context.createWebhook("create webhook");  // Wait for webhook to be called with 30 second timeout  const webhookResponse = await context.waitForWebhook(    "wait for webhook",    webhook,    "30s"  );  if (webhookResponse.timeout) {    console.log("Webhook was not called within the timeout period");  } else {    console.log("Webhook was called successfully");    console.log("Request body:", webhookResponse.request.body);    console.log("Request headers:", webhookResponse.request.headers);  }});

For more complete examples and use cases, see the page on webhooks.