Webhooks

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

import { serve } from "@upstash/workflow/nextjs";export const { POST } = serve(async (context) => {  // Step 1: Create webhook  const webhook = await context.createWebhook("create webhook");  // Step 2: Call an external endpoint, which calls the webhookUrl upon completion  const callResult = await context.call("call webhook caller", {    url: "https://webhook/caller",    method: "POST",    body: JSON.stringify({      webhookUrl: webhook.webhookUrl,    }),  });  // Step 3: Wait for the webhook to be called  const webhookResponse = await context.waitForWebhook(    "wait for webhook",    webhook,    "30s" // timeout  );  if (webhookResponse.timeout) {    console.log("Webhook was not called in time");    // Handle timeout scenario  } else {    console.log("Webhook received:", webhookResponse.request);    // Process the webhook data  }});

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:

while (true) {  const webhookResponse = await context.waitForWebhook(    `wait for progress update ${stepCount}`,    webhook,    "5m" // 5 minute timeout between updates  );  if (webhookResponse.timeout) {    console.log("No progress update received in time, exiting");    break;  } else {    const request = webhookResponse.request;    console.log("Progress update received:", await request.json());    if (request.headers.get("x-task-finished") === "true") {      console.log("Task finished, exiting loop");      break;    }  }}

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