Human-in-the-Loop with Chat SDK and Workflow SDK

You can pause a durable workflow until a human approves it in Slack by combining Chat SDK and Workflow SDK. Chat SDK posts an interactive card with Approve and Deny buttons; Workflow SDK's createWebhook generates a URL that those buttons POST to when clicked, suspending the workflow until the click arrives. The workflow resumes with the click payload, decides what to do, and continues, with no onAction handler, no custom approval database, and no polling.

This guide will walk you through suspending a workflow with createWebhook, posting a Chat SDK approval card with callbackUrl buttons, and resuming the workflow based on the user's choice. You'll add a timeout so abandoned approvals can't suspend forever, and see how to extend the pattern to multiple decision points within a single workflow.

Before you begin, make sure you have:

• Node.js 18 or later
• An existing Chat SDK bot (see the Slack agent guide or Slack file bot guide)
• A project configured for Workflow SDK
• A Vercel account if you're deploying to Vercel

Three pieces fit together:

• Workflow SDK runs the long-lived process. A function becomes durable when you mark it with "use workflow": it can suspend, resume, and survive crashes without losing state. createWebhook() returns an object with a url that's a public endpoint. When you await it, the workflow is suspended until that endpoint receives an HTTP request.
• Chat SDK presents the decision to a human. A <Button callbackUrl="..."> posts the click's action data to the URL you supply, in addition to firing any onAction handler. When the URL is the workflow's webhook.url, the click resumes the workflow directly.
• The pairing removes the usual glue. There's no separate approvals table, no onAction callback that has to look up which workflow is waiting, and no polling. The workflow suspends, the user clicks, and the same workflow function picks up where it left off with the click payload in hand.

createWebhook() is the right primitive when the workflow itself owns the resume URL. For cases where you'd rather keep the URL private and resume from your own server code, use createHook() with a deterministic business token instead.

Add Workflow SDK to a project that already has a Chat SDK bot set up:

pnpm add workflow

If you're starting from scratch, also install a few Chat SDK packages:

pnpm add chat @chat-adapter/slack @chat-adapter/state-redis

The workflow package is Workflow SDK's core. The chat package is the Chat SDK core, and @chat-adapter/slack and @chat-adapter/state-redis are the Slack platform adapter and Redis state adapter. See the Chat SDK getting started guide and Slack agent guide if you don't have a bot yet.

Create workflows/approval.ts:

import { createWebhook } from "workflow";
import {
  finalizeApprovalCard,
  postApprovalCard,
  postReply,
} from "@/lib/slack";

export async function requestDeployApproval(opts: {
  threadId: string;
  version: string;
  requestedBy: string;
}) {
  "use workflow";

  using webhook = createWebhook();

  const messageId = await postApprovalCard({
    threadId: opts.threadId,
    version: opts.version,
    requestedBy: opts.requestedBy,
    webhookUrl: webhook.url,
  });

  const request = await webhook;
  const payload = await request.json();

  if (payload.actionId === "approve") {

    await deploy(opts.version);
    await finalizeApprovalCard({
      threadId: opts.threadId,
      messageId,
      version: opts.version,
      requestedBy: opts.requestedBy,
      outcome: `Approved by <@${payload.user.id}> — ${opts.version} deployed.`,
    });

    await postReply(
      opts.threadId,
      `Deployed **${opts.version}** by <@${payload.user.id}>.`,
    );

  } else {

    await finalizeApprovalCard({
      threadId: opts.threadId,
      messageId,
      version: opts.version,
      requestedBy: opts.requestedBy,
      outcome: `Denied by <@${payload.user.id}>.`,
    });

    await postReply(
      opts.threadId,
      `Deploy of **${opts.version}** denied by <@${payload.user.id}>.`,
    );
  }

}

async function deploy(version: string) {
  "use step";
  // Trigger your deploy here. This runs as a durable step,
  // so retries and observability come for free.
}

The workflow is intentionally thin. It owns the webhook and the resume logic; everything else (posting the card, sending follow-up messages, triggering the deploy) is a step. That separation keeps the workflow body deterministic and pushes side effects into retryable units.

Next, define the helper steps in lib/slack.ts:

import { Card, CardText, Actions, Button } from "chat";
import { bot } from "@/lib/bot";

export async function postApprovalCard(opts: {
  threadId: string;
  version: string;
  requestedBy: string;
  webhookUrl: string;
}): Promise<string> {
  "use step";

  const thread = bot.thread(opts.threadId);
  const sent = await thread.post(
    <Card title={`Deploy ${opts.version}?`} subtitle={`Requested by ${opts.requestedBy}`}>
      <CardText>Approve to roll out **{opts.version}**, or deny to abort.</CardText>
      <Actions>
        <Button id="approve" style="primary" callbackUrl={opts.webhookUrl}>
          Approve
        </Button>
        <Button id="deny" style="danger" callbackUrl={opts.webhookUrl}>
          Deny
        </Button>
      </Actions>
    </Card>,
  );
  return sent.id;
}

// Re-render the approval card without the Actions block, swapping the
// buttons for a static outcome line. The title, subtitle, and body text
// stay the same so the thread keeps its context.
export async function finalizeApprovalCard(opts: {
  threadId: string;
  messageId: string;
  version: string;
  requestedBy: string;
  outcome: string;
}) {
  "use step";

  const thread = bot.thread(opts.threadId);
  await thread.adapter.editMessage(
    thread.id,
    opts.messageId,
    <Card title={`Deploy ${opts.version}?`} subtitle={`Requested by ${opts.requestedBy}`}>
      <CardText>Approve to roll out **{opts.version}**, or deny to abort.</CardText>
      <CardText>{opts.outcome}</CardText>
    </Card>,
  );
}

// Post a follow-up message as markdown so platforms with native markdown
// support render bold/italic/links instead of literal asterisks. Plain
// strings are passed through as-is — `{ markdown }` is the explicit form.
export async function postReply(threadId: string, markdown: string) {
  "use step";
  await bot.thread(threadId).post({ markdown });
}

bot.thread(threadId) constructs a Thread reference from a serialized ID, which is exactly the entry point Chat SDK provides for posting outside an event handler. Thread IDs follow the format adapter:channel:thread (for example, slack:C123ABC:1234567890.123456) and round-trip cleanly through JSON, so they're safe to pass as workflow inputs.

A few things to notice:

• The using declaration ensures the webhook is cleaned up automatically when the workflow exits, even if it throws.
• Both buttons point at the same webhook.url. The actionId travels in the callback payload, so a single webhook handles all the buttons on the card.
• await webhook suspends the workflow. The function pauses here until the user clicks, which could take seconds, hours, or days. Workflow SDK persists the state and resumes on the click.
• The deploy function is marked "use step", which makes it a durable step with automatic retries and observability. Workflow SDK only re-runs steps when they fail, not on resume, so approval and deploy stay clean.
• postApprovalCard returns the posted message's id, and finalizeApprovalCard calls thread.adapter.editMessage to re-render the card without buttons once the decision is in. That prevents a stale click on the original card from hitting the consumed webhook, and it leaves a clear audit trail in the thread.
• postReply posts with { markdown } rather than a bare string. The bare-string form is passed through as-is, so **bold** would render as literal asterisks on Slack and Teams; the { markdown } form is converted to the platform's native markup.

If you need to preserve more of the original thread context across the workflow boundary (for example, the triggering message or thread metadata), use thread.toJSON() on the way in and bot.reviver() when restoring on the other side. For the approval flow above, the thread ID is enough.

Trigger the workflow from wherever the approval request originates.

From a Chat SDK handler:

1
import { start } from "workflow/api";
2
import { requestDeployApproval } from "@/workflows/approval";
3

4
bot.onNewMention(async (thread, message) => {
5
  const version = parseVersion(message.text);
6
  if (!version) {
7
    await thread.post("Usage: @bot deploy v1.2.3");
8
    return;
9
  }
10
  await start(requestDeployApproval, [
11
    {
12
      threadId: thread.id,
13
      version,
14
      requestedBy: message.author.fullName,
15
    },
16
  ]);
17
});

start queues the workflow run and returns immediately with a run handle, allowing the mention handler to respond without blocking. The workflow takes over from there, posting the card, suspending on the webhook, and resuming when the user clicks.

Chat SDK POSTs a JSON body to the callback URL with this shape:

{
  "type": "action",
  "actionId": "approve",
  "value": "approve",
  "user": { "id": "U123", "name": "alice" },
  "threadId": "slack:C123:1234567890.123",
  "messageId": "1234567890.456"
}

actionId is the button's id prop. value is whatever you passed to value. user is the user who clicked, regardless of who triggered the workflow. Use actionId to branch on which button was pressed, and user.id to record or validate who approved.

For workflows that need more than one approval, call createWebhook() multiple times. Each call generates a fresh URL, so suspensions are independent:

1
export async function multiStageApproval(opts: { threadId: string }) {
2
  "use workflow";
3

4
  using draftReview = createWebhook();
5
  const draftTitle = "Approve draft?";
6
  const draftMessageId = await postPrompt(opts.threadId, draftTitle, draftReview.url);
7
  const draftPayload = await (await draftReview).json();
8
  if (draftPayload.actionId !== "approve") {
9
    await finalizePromptCard(opts.threadId, draftMessageId, draftTitle, `Rejected by <@${draftPayload.user.id}>.`);
10
    return;
11
  }
12
  await finalizePromptCard(opts.threadId, draftMessageId, draftTitle, `Approved by <@${draftPayload.user.id}>.`);
13

14
  using finalReview = createWebhook();
15
  const finalTitle = "Approve final?";
16
  const finalMessageId = await postPrompt(opts.threadId, finalTitle, finalReview.url);
17
  const finalPayload = await (await finalReview).json();
18
  if (finalPayload.actionId !== "approve") {
19
    await finalizePromptCard(opts.threadId, finalMessageId, finalTitle, `Rejected by <@${finalPayload.user.id}>.`);
20
    return;
21
  }
22
  await finalizePromptCard(opts.threadId, finalMessageId, finalTitle, `Approved by <@${finalPayload.user.id}>.`);
23

24
  await publish();
25
}

postPrompt is a step function shaped like postApprovalCard from earlier, generalized to accept any prompt text and return the posted messageId. finalizePromptCard is the matching edit helper; it re-renders the card with the same title, replacing the buttons with an outcome line. Each using declaration scopes the webhook to its block, so cleanup happens as soon as the workflow moves past that approval, and the rendered card matches: every stage shows its final state without leaving stale buttons in the thread. The workflow itself can suspend at any point without you tracking which webhook is which, since the runtime handles that.

A workflow that suspends on a webhook indefinitely is fine until someone forgets to click. Race the webhook against a durable sleep to bound the wait:

1
import { createWebhook, sleep } from "workflow";
2

3
export async function approvalWithTimeout(opts: { threadId: string }) {
4
  "use workflow";
5

6
  using webhook = createWebhook();
7
  const title = "Proceed with the change?";
8
  const messageId = await postPrompt(opts.threadId, title, webhook.url);
9

10
  const result = await Promise.race([
11
    webhook.then(async (req) => ({ kind: "clicked" as const, body: await req.json() })),
12
    sleep("24h").then(() => ({ kind: "timeout" as const })),
13
  ]);
14

15
  if (result.kind === "timeout") {
16
    await finalizePromptCard(opts.threadId, messageId, title, "Timed out after 24h — no decision recorded.");
17
    return;
18
  }
19

20
  await finalizePromptCard(
21
    opts.threadId,
22
    messageId,
23
    title,
24
    `${result.body.actionId === "approve" ? "Approved" : "Denied"} by <@${result.body.user.id}>.`,
25
  );
26

27
  if (result.body.actionId === "approve") {
28
    await proceed();
29
  }
30
}

sleep is itself a durable suspension, so the 24-hour wait costs nothing while it's pending and survives deploys. When the timeout wins the race, the workflow continues without resuming the webhook, and the using cleanup releases the URL. The card is finalized in both branches, so the timeout is visible in the thread rather than silently leaving a stale set of buttons.

The callback URL is authenticated only by its token, which means anyone who can intercept the URL can resume the workflow. For sensitive operations, validate the user in the payload before continuing:

1
const APPROVERS = new Set(["U_ALICE", "U_BOB"]);
2

3
const request = await webhook;
4
const payload = await request.json();
5

6
if (!APPROVERS.has(payload.user.id)) {
7
  await thread.post(
8
    `<@${payload.user.id}> isn't authorized to approve this deploy.`,
9
  );
10
  return;
11
}

For stronger guarantees, switch to createHook() and resume the workflow from your own authenticated route with resumeHook(). That pattern keeps the resume URL private and gives you full control over the authorization check, at the cost of writing a route handler.

Confirm the button's callbackUrl matches webhook.url exactly. The URL contains a token that's bound to the suspension, so a stale or hand-edited URL won't resolve. Check the Workflow SDK CLI to see whether the workflow is still suspended on the webhook:

npx workflow inspect runs --web

If the click reached the URL but the workflow didn't move, look for an error in the workflow logs. The using declaration disposes the webhook on the next throw, so an uncaught error in the workflow body can release the URL before the click arrives.

Discord's custom_id has a 100-character limit; Telegram's callback_data has a 64-byte limit. The encoded button data is the action ID plus the callback token, which can exceed those caps. Shorten the action ID ("a" instead of "approve-deploy-v1-2-3") and move long context into value or out of the card entirely. Slack and Teams don't have this limit.

The main flow above guards against this by calling finalizeApprovalCard immediately after the decision lands. The card is re-rendered without its Actions block, so there's nothing left to click. If you skip that step, Chat SDK won't dedupe clicks for you: once await webhook has resolved, a second click hits a webhook that no longer exists, and the user sees the platform's default error. Either edit the card to remove the buttons (the pattern shown above, via thread.adapter.editMessage), or accept that only the first click matters and ignore the rest.

Workflows suspend until something resumes them. If your callback URL was lost (for example, a card was deleted before anyone could click), the run will stay suspended until its associated webhook is cleaned up. Use a timeout (see above) to bound every suspension, and use the Workflow SDK CLI to cancel runs that should no longer wait:

npx workflow inspect runs
# find the run ID, then:
npx workflow runs cancel <run-id>

• Chat SDK Threads, Messages, and Channels
• Chat SDK Actions
• Workflow SDK createWebhook
• Workflow SDK createHook
• Workflow SDK Human-in-the-Loop example
• How to build an AI agent for Slack with Chat SDK and AI SDK