Temporal Human-in-the-Loop with an Approval Inbox

A Temporal workflow waits for a human with a signal and a durable timer. Impri adds the approval inbox: a signed webhook wakes it when someone decides.

Updated 2026-11-16. Tested with the Temporal TypeScript SDK 1.25.0 on a local dev server, against a self-hosted Impri server.


What Temporal gives you, and what it leaves to you

Temporal's own human-in-the-loop recipe pauses the workflow with wait_condition until a Signal brings the decision or a timeout runs out (5 minutes by default). The wait survives worker restarts and uses no compute while it lasts.

In the recipe, the "UI" is a script you run in a terminal to send the signal. In production a person has to see the proposed action, perhaps fix the wording, and answer from wherever they are. You also want an expiry and a record of who decided. That part is Impri's:

Concern Temporal Impri
Durable wait, retries, resume yes no
Card with the proposed action, editable text no yes
Reach the reviewer (web inbox, Slack, Discord, Telegram) no yes
Nobody answers your timer expires_in, then status expired
Who decided, when workflow history audit log
Running the action your activity never

Impri is only the gate. It stores the proposal, notifies a human and records the answer. Your activities do the work.


How the pieces connect

  1. An activity creates the Impri card with an idempotency_key and a callback_url that carries the workflow ID.
  2. The workflow waits on condition() for a signal, with a 15-minute timer as a fallback.
  3. A reviewer decides. Impri POSTs a signed webhook to your receiver; deliveries go out on a 60-second tick.
  4. The receiver checks the signature and signals the workflow with the action ID.
  5. The workflow reads the verdict from GET /v1/actions/:id, sends the approved text with any edits, and reports the result.

The signal is only a wake-up call. The verdict always comes from Impri's API with your key, so a forged or replayed request to the receiver can't approve anything. That's also why the unsigned workflow_id in the query string is safe: a workflow only reacts to its own action ID, and only by re-reading Impri.


Activities

ts
// activities.ts
const BASE = process.env.IMPRI_BASE_URL ?? "https://api.impri.dev";
const headers = {
  Authorization: `Bearer ${process.env.IMPRI_API_KEY}`,
  "Content-Type": "application/json",
};

export interface ImpriAction {
  id: string;
  status: "pending" | "approved" | "rejected" | "expired" | "executed" | "execute_failed";
  decision?: { verdict: "approve" | "reject"; final_preview?: { body: string } };
}

export async function requestApproval(
  title: string,
  draft: string,
  workflowId: string,
  idempotencyKey: string,
): Promise<string> {
  const res = await fetch(`${BASE}/v1/actions`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      kind: "email.send",
      title,
      preview: { format: "markdown", body: draft },
      editable: ["preview.body"],
      expires_in: 86400, // 24 h, then the card expires and the webhook fires
      idempotency_key: idempotencyKey, // a retried activity gets the same card back
      callback_url: `${process.env.WEBHOOK_URL}?workflow_id=${encodeURIComponent(workflowId)}`,
    }),
  });
  if (!res.ok) throw new Error(`Impri create failed: ${res.status}`);
  return (await res.json()).id;
}

export async function getAction(id: string): Promise<ImpriAction> {
  const res = await fetch(`${BASE}/v1/actions/${id}`, { headers });
  if (!res.ok) throw new Error(`Impri fetch failed: ${res.status}`);
  return res.json();
}

export async function reportResult(id: string, status: "executed" | "execute_failed") {
  const res = await fetch(`${BASE}/v1/actions/${id}/result`, {
    method: "POST",
    headers,
    body: JSON.stringify({ status }),
  });
  // 409: the result is already recorded (this is a retry after a lost response)
  if (!res.ok && res.status !== 409) throw new Error(`Impri result failed: ${res.status}`);
}

export async function sendEmail(body: string): Promise<void> {
  // your side effect: the only code path that sends
}

Workflow

ts
// workflows.ts
import { condition, defineSignal, proxyActivities, setHandler, workflowInfo } from "@temporalio/workflow";
import type * as activities from "./activities";

const { requestApproval, getAction, reportResult } = proxyActivities<typeof activities>({
  startToCloseTimeout: "30 seconds",
});
const { sendEmail } = proxyActivities<typeof activities>({
  startToCloseTimeout: "30 seconds",
  retry: { maximumAttempts: 3 },
});

export const impriDecided = defineSignal<[string]>("impriDecided");

export async function refundEmailWorkflow(title: string, draft: string): Promise<string> {
  const { workflowId, runId } = workflowInfo();
  const actionId = await requestApproval(title, draft, workflowId, `${workflowId}:${runId}`);

  let woken = false;
  setHandler(impriDecided, (id) => {
    if (id === actionId) woken = true;
  });

  let action = await getAction(actionId);
  while (action.status === "pending") {
    // The webhook wakes us within about a minute; the timer covers a lost delivery.
    await condition(() => woken, "15 minutes");
    woken = false;
    action = await getAction(actionId); // the verdict comes from Impri, not the signal
  }

  if (action.status !== "approved") return action.status; // rejected | expired

  try {
    await sendEmail(action.decision!.final_preview!.body); // includes reviewer edits
  } catch (err) {
    await reportResult(actionId, "execute_failed");
    throw err;
  }
  await reportResult(actionId, "executed");
  return "executed";
}

Webhook receiver

ts
// webhook.ts: receives Impri's decision callback and wakes the workflow
import http from "node:http";
import { createHmac, timingSafeEqual } from "node:crypto";
import { Client, Connection, WorkflowNotFoundError } from "@temporalio/client";
import { impriDecided } from "./workflows";

const SECRET = process.env.IMPRI_WEBHOOK_SECRET!; // webhook_secret from GET /v1/project

function signedByImpri(raw: string, h: http.IncomingHttpHeaders): boolean {
  const ts = String(h["x-impri-timestamp"] ?? "");
  const nonce = String(h["x-impri-nonce"] ?? "");
  const sig = String(h["x-impri-signature"] ?? "");
  if (!(Math.abs(Date.now() / 1000 - Number(ts)) <= 300)) return false; // stale or missing
  const expected = "sha256=" + createHmac("sha256", SECRET).update(`${ts}.${nonce}.${raw}`).digest("hex");
  return sig.length === expected.length && timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

const client = new Client({
  connection: await Connection.connect({ address: process.env.TEMPORAL_ADDRESS ?? "localhost:7233" }),
});

http
  .createServer(async (req, res) => {
    const url = new URL(req.url ?? "/", "http://localhost");
    const workflowId = url.searchParams.get("workflow_id");
    if (req.method !== "POST" || !workflowId) {
      res.writeHead(404).end();
      return;
    }
    const chunks: Buffer[] = [];
    for await (const chunk of req) chunks.push(chunk as Buffer);
    const raw = Buffer.concat(chunks).toString("utf8");

    if (!signedByImpri(raw, req.headers)) {
      res.writeHead(401).end();
      return;
    }
    try {
      await client.workflow.getHandle(workflowId).signal(impriDecided, JSON.parse(raw).action_id);
    } catch (err) {
      if (!(err instanceof WorkflowNotFoundError)) {
        res.writeHead(503).end(); // Impri retries: 1 min, 5 min, 25 min, 2 h, 12 h
        return;
      }
    }
    res.writeHead(200).end();
  })
  .listen(Number(process.env.PORT ?? 8080));

IMPRI_WEBHOOK_SECRET is the project's webhook_secret from GET /v1/project (admin key); POST /v1/project/rotate-webhook-secret replaces it. The receiver must be reachable from Impri over public http(s): Impri doesn't deliver to private addresses unless a self-hosted server sets IMPRI_ALLOW_PRIVATE_TARGETS=1.


What we ran

On 2026-11-16, the code above, unchanged, with a test worker (TestWorkflowEnvironment.createLocal()) and an Impri server built from the open-source repo:

Not exercised: the 15-minute fallback and the 24-hour expiry.


Details that matter in production


No public URL?

Leave out callback_url, the receiver and the signal, and shorten the timer to a minute: the loop then polls GET /v1/actions/:id. That's fine for a few waiting workflows; with many, the webhook saves a request per workflow per minute.


Next step

Create a free project on Impri Cloud: the key you get is the project's admin key, so it can create cards and read the webhook_secret. Start one workflow and the card appears in your inbox. Prefer your own infrastructure? Self-hosting runs the same API with Docker Compose. The request and decision fields are explained in how to add human approval to an AI agent, and the webhook format in webhooks.