- 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:- Creates a unique webhook URL via
context.createWebhook() - Provides the URL to external services (typically through
context.call()) - Pauses execution via
context.waitForWebhook()until the webhook is called - Resumes workflow when the webhook receives a request or timeout is reached
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 beforecontext.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