- 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:| Feature | Webhooks | Wait for Event |
|---|---|---|
| Trigger | External HTTP call to unique URL | Notify via Upstash Workflow Client |
| Setup | Create webhook, pass URL to external service | Share event ID with external service |
| Integration | Easy with callback-based APIs | Requires Workflow Client integration |
| Lookback | ✅ Yes - safe against race conditions | ❌ No - notify before wait will be lost |
| Best For | Third-party API callbacks | Internal event notifications |