workflow 4.1.0-beta.63 → 4.2.0-beta.64

package/docs/api-reference/workflow/create-hook.mdx

@@ -100,7 +100,7 @@ export async function slackBotWorkflow(channelId: string) {
 
   // Token constructed from channel ID
   using hook = createHook<SlackMessage>({ // [!code highlight]
-    token: `slack_webhook:${channelId}`, // [!code highlight]
+    token: `slack_messages:${channelId}`, // [!code highlight]
   }); // [!code highlight]
 
   for await (const message of hook) {

package/docs/api-reference/workflow/create-webhook.mdx

@@ -120,46 +120,6 @@ async function processData(data: any) {
 }
 ```
 
-### Customizing Tokens
-
-Tokens are used to identify a specific webhook. You can customize the token to be more specific to a use case.
-
-```typescript lineNumbers
-import { createWebhook, type RequestWithResponse } from "workflow"
-
-async function sendAck(request: RequestWithResponse) {
-  "use step";
-  await request.respondWith(
-    new Response(JSON.stringify({ received: true }), {
-      headers: { "Content-Type": "application/json" }
-    })
-  );
-}
-
-export async function githubWebhookWorkflow(repoName: string) {
-  "use workflow";
-
-  // Use a deterministic token based on the repository
-  using webhook = createWebhook({ // [!code highlight]
-    token: `github_webhook:${repoName}`, // [!code highlight]
-  }); // [!code highlight]
-
-  console.log("Configure GitHub webhook:", webhook.url);
-
-  const request = await webhook;
-  const event = await request.json();
-
-  await sendAck(request);
-
-  await deployCommit(event);
-}
-
-async function deployCommit(event: any) {
-  "use step";
-  // Deploy logic here
-}
-```
-
 ### Waiting for Multiple Requests
 
 You can also wait for multiple requests by using the `for await...of` syntax.
@@ -167,62 +127,35 @@ You can also wait for multiple requests by using the `for await...of` syntax.
 ```typescript lineNumbers
 import { createWebhook, type RequestWithResponse } from "workflow"
 
-async function sendSlackResponse(request: RequestWithResponse, message: string) {
+async function sendAck(request: RequestWithResponse, message: string) {
   "use step";
   await request.respondWith(
-    new Response(
-      JSON.stringify({
-        response_type: "in_channel",
-        text: message
-      }),
-      { headers: { "Content-Type": "application/json" } }
-    )
+    Response.json({ received: true, message })
   );
 }
 
-async function sendStopResponse(request: RequestWithResponse) {
+async function processEvent(data: any) {
   "use step";
-  await request.respondWith(
-    new Response("Stopping workflow...")
-  );
+  console.log("Processing event:", data);
 }
 
-export async function slackCommandWorkflow(channelId: string) {
+export async function eventCollectorWorkflow() {
   "use workflow";
 
-  using webhook = createWebhook({
-    token: `slack_command:${channelId}`,
-  });
+  using webhook = createWebhook({ respondWith: "manual" });
+  console.log("Send events to:", webhook.url);
 
   for await (const request of webhook) { // [!code highlight]
-    const formData = await request.formData();
-    const command = formData.get("command");
-    const text = formData.get("text");
+    const data = await request.json();
 
-    if (command === "/status") {
-      // Respond immediately to Slack
-      await sendSlackResponse(request, "Checking status...");
-
-      // Process the command
-      const status = await checkSystemStatus();
-      await postToSlack(channelId, `Status: ${status}`);
-    }
-
-    if (text === "stop") {
-      await sendStopResponse(request);
+    if (data.type === "done") {
+      await sendAck(request, "Workflow complete");
       break;
     }
-  }
-}
-
-async function checkSystemStatus() {
-  "use step";
-  return "All systems operational";
-}
 
-async function postToSlack(channelId: string, message: string) {
-  "use step";
-  // Post message to Slack
+    await sendAck(request, "Event received");
+    await processEvent(data);
+  }
 }
 ```
 

package/docs/api-reference/workflow-api/resume-webhook.mdx

@@ -56,11 +56,17 @@ Returns a `Promise<Response>` that resolves to:
 
 Throws an error if the webhook token is not found or invalid.
 
-## Examples
+## Usage Note
 
-### Basic API Route
+<Callout type="warn">
+In most cases, you should not need to call `resumeWebhook()` directly. When you use `createWebhook()`, the framework automatically generates a random webhook token and provides a public URL at `/.well-known/workflow/v1/webhook/:token`. External systems can send HTTP requests directly to that URL.
+
+For server-side hook resumption with deterministic tokens, use [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) with [`createHook()`](/docs/api-reference/workflow/create-hook) instead.
+</Callout>
 
-Forward incoming HTTP requests to a webhook by token:
+## Example
+
+Forward an incoming HTTP request to a webhook by token:
 
 ```typescript lineNumbers
 import { resumeWebhook } from "workflow/api";
@@ -82,159 +88,6 @@ export async function POST(request: Request) {
 }
 ```
 
-### GitHub Webhook Handler
-
-Handle GitHub webhook events and forward them to workflows:
-
-```typescript lineNumbers
-import { resumeWebhook } from "workflow/api";
-import { verifyGitHubSignature } from "@/lib/github";
-
-export async function POST(request: Request) {
-  // Extract repository name from URL
-  const url = new URL(request.url);
-  const repo = url.pathname.split("/").pop();
-
-  // Verify GitHub signature
-  const signature = request.headers.get("x-hub-signature-256");
-  const isValid = await verifyGitHubSignature(request, signature);
-
-  if (!isValid) {
-    return new Response("Invalid signature", { status: 401 });
-  }
-
-  // Construct deterministic token
-  const token = `github_webhook:${repo}`;
-
-  try {
-    const response = await resumeWebhook(token, request); // [!code highlight]
-    return response;
-  } catch (error) {
-    return new Response("Workflow not found", { status: 404 });
-  }
-}
-```
-
-### Slack Slash Command Handler
-
-Process Slack slash commands and route them to workflow webhooks:
-
-```typescript lineNumbers
-import { resumeWebhook } from "workflow/api";
-
-export async function POST(request: Request) {
-  const formData = await request.formData();
-  const channelId = formData.get("channel_id") as string;
-  const command = formData.get("command") as string;
-
-  // Verify Slack request signature
-  const slackSignature = request.headers.get("x-slack-signature");
-  if (!slackSignature) {
-    return new Response("Unauthorized", { status: 401 });
-  }
-
-  // Construct token from channel ID
-  const token = `slack_command:${channelId}`;
-
-  try {
-    const response = await resumeWebhook(token, request); // [!code highlight]
-    return response;
-  } catch (error) {
-    // If no workflow is listening, return a default response
-    return new Response(
-      JSON.stringify({
-        response_type: "ephemeral",
-        text: "No active workflow for this channel"
-      }),
-      {
-        headers: { "Content-Type": "application/json" }
-      }
-    );
-  }
-}
-```
-
-### Multi-Tenant Webhook Router
-
-Route webhooks to different workflows based on tenant/organization:
-
-```typescript lineNumbers
-import { resumeWebhook } from "workflow/api";
-
-export async function POST(request: Request) {
-  const url = new URL(request.url);
-
-  // Extract tenant and webhook ID from path
-  // e.g., /api/webhooks/tenant-123/webhook-abc
-  const [, , , tenantId, webhookId] = url.pathname.split("/");
-
-  if (!tenantId || !webhookId) {
-    return new Response("Invalid webhook URL", { status: 400 });
-  }
-
-  // Verify API key for tenant
-  const apiKey = request.headers.get("authorization");
-  const isAuthorized = await verifyTenantApiKey(tenantId, apiKey);
-
-  if (!isAuthorized) {
-    return new Response("Unauthorized", { status: 401 });
-  }
-
-  // Construct namespaced token
-  const token = `tenant:${tenantId}:webhook:${webhookId}`;
-
-  try {
-    const response = await resumeWebhook(token, request); // [!code highlight]
-    return response;
-  } catch (error) {
-    return new Response("Webhook not found or expired", { status: 404 });
-  }
-}
-
-async function verifyTenantApiKey(tenantId: string, apiKey: string | null) {
-  // Verify API key logic
-  return apiKey === process.env[`TENANT_${tenantId}_API_KEY`];
-}
-```
-
-### Server Action (Next.js)
-
-Use `resumeWebhook` in a Next.js server action:
-
-```typescript lineNumbers
-"use server";
-
-import { resumeWebhook } from "workflow/api";
-
-export async function triggerWebhook(
-  token: string,
-  payload: Record<string, any>
-) {
-  // Create a Request object from the payload
-  const request = new Request("http://localhost/webhook", {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify(payload),
-  });
-
-  try {
-    const response = await resumeWebhook(token, request);
-
-    // Parse and return the response
-    const contentType = response.headers.get("content-type");
-    if (contentType?.includes("application/json")) {
-      return await response.json();
-    }
-
-    return await response.text();
-  } catch (error) {
-    throw new Error("Webhook not found");
-  }
-}
-```
-
 ## Related Functions
 
 - [`createWebhook()`](/docs/api-reference/workflow/create-webhook) - Create a webhook in a workflow

package/docs/foundations/hooks.mdx

@@ -339,53 +339,36 @@ Like hooks, webhooks support iteration:
 ```typescript lineNumbers
 import { createWebhook, type RequestWithResponse } from "workflow";
 
-async function respondToSlack(request: RequestWithResponse, text: string) {
+async function sendAck(request: RequestWithResponse, message: string) {
   "use step";
 
   await request.respondWith(
-    new Response(
-      JSON.stringify({ response_type: "in_channel", text }),
-      { headers: { "Content-Type": "application/json" } }
-    )
+    Response.json({ received: true, message })
   );
 }
 
-export async function slackCommandWorkflow(channelId: string) {
-  "use workflow";
+async function processEvent(data: any) {
+  "use step";
+  console.log("Processing event:", data);
+}
 
-  using webhook = createWebhook({
-    token: `slack_command:${channelId}`,
-    respondWith: "manual"
-  });
+export async function eventCollectorWorkflow() {
+  "use workflow";
 
-  console.log("Configure Slack command webhook:", webhook.url);
+  using webhook = createWebhook({ respondWith: "manual" });
+  console.log("Send events to:", webhook.url);
 
   for await (const request of webhook) {
-    const formData = await request.formData();
-    const command = formData.get("command");
-    const text = formData.get("text");
-
-    if (command === "/status") {
-      await respondToSlack(request, "Checking status...");
-      const status = await checkSystemStatus();
-      await postToSlack(channelId, `Status: ${status}`);
-    }
+    const data = await request.json();
 
-    if (text === "stop") {
-      await respondToSlack(request, "Stopping workflow...");
+    if (data.type === "done") {
+      await sendAck(request, "Workflow complete");
       break;
     }
-  }
-}
 
-async function checkSystemStatus() {
-  "use step";
-  return "All systems operational";
-}
-
-async function postToSlack(channelId: string, message: string) {
-  "use step";
-  // Post message to Slack
+    await sendAck(request, "Event received");
+    await processEvent(data);
+  }
 }
 ```
 
@@ -464,7 +447,9 @@ This pattern is especially valuable in larger applications where the workflow an
 
 ### Token Design
 
-When using custom tokens:
+Custom tokens are available for `createHook()` with server-side `resumeHook()` only. Webhooks (`createWebhook()`) always use randomly generated tokens to prevent unauthorized access to public webhook endpoints.
+
+When using custom tokens with `createHook()`:
 
 - **Make them deterministic**: Base them on data the external system can reconstruct (like channel IDs, user IDs, etc.)
 - **Use namespacing**: Prefix tokens to avoid conflicts (e.g., `slack:${channelId}`, `github:${repoId}`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "4.1.0-beta.63",
+  "version": "4.2.0-beta.64",
   "description": "Workflow DevKit - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -52,17 +52,17 @@
   },
   "dependencies": {
     "ms": "2.1.3",
-    "@workflow/astro": "4.0.0-beta.37",
-    "@workflow/cli": "4.1.0-beta.63",
-    "@workflow/core": "4.1.0-beta.63",
-    "@workflow/errors": "4.1.0-beta.17",
+    "@workflow/astro": "4.0.0-beta.38",
+    "@workflow/cli": "4.2.0-beta.64",
+    "@workflow/core": "4.2.0-beta.64",
+    "@workflow/errors": "4.1.0-beta.18",
     "@workflow/typescript-plugin": "4.0.1-beta.5",
-    "@workflow/next": "4.0.1-beta.59",
-    "@workflow/nest": "0.0.0-beta.12",
-    "@workflow/nitro": "4.0.1-beta.58",
-    "@workflow/nuxt": "4.0.1-beta.47",
-    "@workflow/sveltekit": "4.0.0-beta.52",
-    "@workflow/rollup": "4.0.0-beta.20"
+    "@workflow/next": "4.0.1-beta.60",
+    "@workflow/nest": "0.0.0-beta.13",
+    "@workflow/nitro": "4.0.1-beta.59",
+    "@workflow/nuxt": "4.0.1-beta.48",
+    "@workflow/sveltekit": "4.0.0-beta.53",
+    "@workflow/rollup": "4.0.0-beta.21"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",