Skip to main content
The Webhook feature allows you to pause workflow execution and wait for a webhook URL to be called, enabling seamless integration with third-party APIs and asynchronous operations. This feature is perfect for scenarios where you need to:
  • Wait for external API processing to complete
  • Integrate with services that use callback URLs
  • Receive notifications from external webhooks

How Webhooks Work

When you use webhooks in your workflow, Upstash Workflow:
  1. Creates a unique webhook URL via context.createWebhook()
  2. Provides the URL to external services (typically through context.call())
  3. Pauses execution via context.waitForWebhook() until the webhook is called
  4. Resumes workflow when the webhook receives a request or timeout is reached
This happens without keeping your serverless function running, making it cost-effective for long-running integrations.

Examples

Basic Usage

Waiting for Multiple Calls

Some services send multiple progress updates to a webhook URL as processing continues. You can wait for the same webhook multiple times in a loop until you receive a final “finished” signal:

Race Condition Safety

Webhooks have built-in lookback protection, making them safer against race conditions. If an external service calls the webhook URL before context.waitForWebhook() is executed, the webhook call is stored and will be returned when waitForWebhook is called. This means you don’t need to worry about timing issues between creating the webhook and waiting for it - the workflow will always receive the callback even if it arrives early.

Comparison with Wait for Event

Webhooks and Wait for Event serve similar purposes but with different approaches: Choose webhooks when integrating with external services that support callback URLs, or when you need protection against race conditions. Choose Wait for Event when you have control over the notification mechanism and can use the Workflow Client.

API Reference

context.createWebhook

Create a unique webhook URL for external services to call

context.waitForWebhook

Wait for the webhook to be called or timeout