[V0_FILE]typescriptreact:file="app/components/demo.tsx" "use client"; import { useState, useCallback, useRef, useEffect, useMemo } from "react"; // ── Types ─────────────────────────────────────────────────────────────── type PaymentEventType = | "payment.created" | "payment.requires_action" | "payment.succeeded" | "payment.failed" | "refund.created"; interface FeedEntry { id: string; type: PaymentEventType; amount?: number; response: string; timestamp: number; } type Status = "idle" | "listening" | "settled"; type HighlightState = | "none" | "connect" | "payment.created" | "payment.requires_action" | "payment.succeeded" | "payment.failed" | "refund.created" | "done"; // Phase drives which buttons are enabled type Phase = | "init" // only payment.created | "created" // requires_action, succeeded, failed | "action_required" // succeeded, failed | "failed" // payment.created (retry) | "succeeded" // refund.created + Complete Order ; const PHASE_EVENTS: Record> = { init: new Set(["payment.created"]), created: new Set(["payment.requires_action", "payment.succeeded", "payment.failed"]), action_required: new Set(["payment.succeeded", "payment.failed"]), failed: new Set(["payment.created"]), succeeded: new Set(["refund.created"]), }; const EVENT_TO_PHASE: Partial> = { "payment.created": "created", "payment.requires_action": "action_required", "payment.succeeded": "succeeded", "payment.failed": "failed", }; // ── Event config ──────────────────────────────────────────────────────── const EVENTS: { type: PaymentEventType; label: string; dot: string; border: string; }[] = [ { type: "payment.created", label: "Payment Created", dot: "bg-blue-700", border: "border-blue-700/30 hover:border-blue-700/60", }, { type: "payment.requires_action", label: "Requires Action", dot: "bg-purple-700", border: "border-purple-700/30 hover:border-purple-700/60", }, { type: "payment.succeeded", label: "Payment Succeeded", dot: "bg-green-700", border: "border-green-700/30 hover:border-green-700/60", }, { type: "payment.failed", label: "Payment Failed", dot: "bg-red-700", border: "border-red-700/30 hover:border-red-700/60", }, { type: "refund.created", label: "Refund Created", dot: "bg-amber-700", border: "border-amber-700/30 hover:border-amber-700/60", }, ]; const DOT_COLOR: Record = { "payment.created": "bg-blue-700", "payment.requires_action": "bg-purple-700", "payment.succeeded": "bg-green-700", "payment.failed": "bg-red-700", "refund.created": "bg-amber-700", }; const TEXT_COLOR: Record = { "payment.created": "text-blue-700", "payment.requires_action": "text-purple-700", "payment.succeeded": "text-green-700", "payment.failed": "text-red-700", "refund.created": "text-amber-700", }; const HL_COLOR: Record = { connect: "border-blue-700 bg-blue-700/10", "payment.created": "border-blue-700 bg-blue-700/10", "payment.requires_action": "border-purple-700 bg-purple-700/10", "payment.succeeded": "border-green-700 bg-green-700/10", "payment.failed": "border-red-700 bg-red-700/10", "refund.created": "border-amber-700 bg-amber-700/10", done: "border-green-700 bg-green-700/10", }; const HL_LABEL: Record = { none: "Click an event to trace the code path", connect: "createWebhook() \u2192 registers a durable endpoint", "payment.created": "payment.created \u2192 charge received", "payment.requires_action": "payment.requires_action \u2192 awaiting 3DS / customer auth", "payment.succeeded": "payment.succeeded \u2192 captured \u2014 listening for refund at zero compute", "payment.failed": "payment.failed \u2192 flagged for review", "refund.created": "refund.created \u2192 refunded, order settled", done: "Workflow returned \u2014 order settled", }; // ── Props ─────────────────────────────────────────────────────────────── interface Props { orchestratorHtmlLines: string[]; orchestratorLineMap: Record; stepHtmlLines: string[]; stepLineMap: Record; } // ── Component ─────────────────────────────────────────────────────────── export function PaymentWebhookDemo({ orchestratorHtmlLines, orchestratorLineMap, stepHtmlLines, stepLineMap, }: Props) { const [status, setStatus] = useState("idle"); const [runId, setRunId] = useState(null); const [feed, setFeed] = useState([]); const [error, setError] = useState(null); const [busy, setBusy] = useState(false); const [highlight, setHighlight] = useState("none"); const [orderAmount] = useState(() => Math.floor(Math.random() * 49900 + 100)); const [phase, setPhase] = useState("init"); const feedRef = useRef(null); useEffect(() => { feedRef.current?.scrollTo({ top: feedRef.current.scrollHeight, behavior: "smooth", }); }, [feed]); const enabledEvents = PHASE_EVENTS[phase]; // Compute active lines for each pane const activeOrchestratorLines = useMemo(() => { const set = new Set(); if (highlight === "none") return set; if (highlight === "connect") { for (const n of orchestratorLineMap.connect ?? []) set.add(n); return set; } if (highlight === "done") { for (const n of orchestratorLineMap.returnResult ?? []) set.add(n); return set; } // Event types: loop lines in orchestrator for (const n of orchestratorLineMap.loop ?? []) set.add(n); // Only refund.created triggers the break if (highlight === "refund.created") { for (const n of orchestratorLineMap.breakLine ?? []) set.add(n); } return set; }, [highlight, orchestratorLineMap]); const activeStepLines = useMemo(() => { const set = new Set(); if ( highlight === "none" || highlight === "connect" || highlight === "done" ) return set; for (const n of stepLineMap.parse ?? []) set.add(n); for (const n of stepLineMap[highlight] ?? []) set.add(n); return set; }, [highlight, stepLineMap]); // ── Place order ──────────────────────────────────────────────────── const placeOrder = useCallback(async () => { setBusy(true); setError(null); try { const res = await fetch("/api/mock/webhook", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ orderId: "ord-42" }), }); const data = await res.json(); if (!res.ok) throw new Error(data.error); setRunId(data.runId); setStatus("listening"); setFeed([]); setHighlight("connect"); setPhase("init"); } catch (err) { setError(err instanceof Error ? err.message : "Failed to start"); } finally { setBusy(false); } }, []); // ── Send event ────────────────────────────────────────────────────── const sendEvent = useCallback( async (type: PaymentEventType) => { if (!runId) return; setBusy(true); setError(null); try { const amount = orderAmount; const res = await fetch("/api/mock/webhook", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ runId, type, amount }), }); const data = await res.json(); if (!res.ok) throw new Error(data.error); setFeed((prev) => [ ...prev, { id: `${type}-${Date.now()}`, type, amount, response: data.response, timestamp: Date.now(), }, ]); setHighlight(type); // Advance the phase const nextPhase = EVENT_TO_PHASE[type]; if (nextPhase) setPhase(nextPhase); // refund.created is the only terminal event if (type === "refund.created") { setStatus("settled"); setRunId(null); setTimeout(() => setHighlight("done"), 600); } } catch (err) { setError(err instanceof Error ? err.message : "Request failed"); } finally { setBusy(false); } }, [runId, orderAmount] ); // ── Complete order (happy path, no refund) ───────────────────────── const completeOrder = useCallback(async () => { if (!runId) return; setBusy(true); setError(null); try { // Send order.completed to deactivate the server-side listener const res = await fetch("/api/mock/webhook", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ runId, type: "order.completed" }), }); if (!res.ok) { const data = await res.json(); throw new Error(data.error ?? "Failed to complete order"); } setStatus("settled"); setRunId(null); setHighlight("done"); } catch (err) { setError(err instanceof Error ? err.message : "Failed to complete order"); } finally { setBusy(false); } }, [runId]); // ── Reset ─────────────────────────────────────────────────────────── const reset = useCallback(() => { setStatus("idle"); setRunId(null); setFeed([]); setError(null); setBusy(false); setHighlight("none"); setPhase("init"); }, []); // ── Highlight color for current state ─────────────────────────────── const hlColor = HL_COLOR[highlight] ?? "border-blue-700 bg-blue-700/10"; // ── Idle state ──────────────────────────────────────────────────────── if (status === "idle") { return (

Simulates an order{"\u2019"}s payment lifecycle. Watch the code highlight in sync as each event is processed.

{error && (

{error}

)}

); } // ── Active / settled state ────────────────────────────────────────── return (

{error && (

{error}

)} {/* ── Status bar ─────────────────────────────────────────────── */}


            order:ord-42

{status === "listening" ? phase === "succeeded" ? "Paid \u2014 listening for refund" : "Listening \u2014 zero compute" : "Order settled"}

{/* ── Two-column: simulator + feed ───────────────────────────── */}

{/* Event simulator */}

Simulate Event

{EVENTS.map((ev) => ( ))} {/* Complete Order — happy path exit after payment succeeded */} {phase === "succeeded" && status === "listening" && ( )}

{/* Event feed */}

{feed.length === 0 ? (

Click an event to send it to the webhook{"\u2026"}

) : (

{feed.map((entry) => (

{entry.type} {new Date(entry.timestamp).toLocaleTimeString()}

{entry.amount != null && ( ${(entry.amount / 100).toFixed(2)} )} {"\u2192"} {entry.response}

))}

)}

{/* ── Highlight label ──────────────────────────────────────────── */}

{HL_LABEL[highlight]}

{/* ── Side-by-side code panes ──────────────────────────────────── */}

{/* Orchestrator pane */} {/* Step pane */}

); } // ── Code pane sub-component ───────────────────────────────────────────── function CodePane({ filename, label, htmlLines, activeLines, hlColor, }: { filename: string; label: string; htmlLines: string[]; activeLines: Set; hlColor: string; }) { return (

{filename}

{label}

        
          {htmlLines.map((lineHtml, i) => {
            const lineNum = i + 1;
            const isActive = activeLines.has(lineNum);
            return (
              
            );
          })}

); } [V0_FILE]typescriptreact:file="app/components/code-block.tsx" import { highlight } from "sugar-high"; function parseHighlightLines(ranges?: string): Set { if (!ranges) return new Set(); const lines = new Set(); for (const part of ranges.split(",")) { const trimmed = part.trim(); if (trimmed.includes("-")) { const [start, end] = trimmed.split("-").map(Number); for (let i = start; i <= end; i++) lines.add(i); } else { lines.add(Number(trimmed)); } } return lines; } export function CodeBlock({ code, highlight: ranges, }: { code: string; highlight?: string; }) { const html = highlight(code); const lines = html.split("\n"); const active = parseHighlightLines(ranges); return (

      
        {lines.map((lineHtml, i) => (
          
        ))}

); } [V0_FILE]typescriptreact:file="app/layout.tsx" import type { Metadata } from "next"; import { Geist, Geist_Mono } from "next/font/google"; import "./globals.css"; const geistSans = Geist({ variable: "--font-geist-sans", subsets: ["latin"] }); const geistMono = Geist_Mono({ variable: "--font-geist-mono", subsets: ["latin"] }); export const metadata: Metadata = { title: "Payment Webhook \u2014 Workflow DevKit Example", description: "Durable payment webhook listener using Workflow DevKit with manual response handling", }; export default function RootLayout({ children, }: Readonly<{ children: React.ReactNode }>) { return ( Skip to main content {children} ); } [V0_FILE]typescript:file="app/api/webhook/route.ts" import { NextResponse } from "next/server"; import { start } from "workflow/api"; import { paymentWebhook } from "@/workflows/payment-webhook"; export async function POST(request: Request) { let body: Record; try { body = await request.json(); } catch { return NextResponse.json({ error: "Invalid JSON body" }, { status: 400 }); } const orderId = body.orderId; if (!orderId || typeof orderId !== "string") { return NextResponse.json( { error: "orderId is required" }, { status: 400 } ); } try { const run = await start(paymentWebhook, [orderId]); return NextResponse.json({ runId: run.runId, orderId }); } catch (error) { const message = error instanceof Error ? error.message : "Unknown error"; return NextResponse.json({ error: message }, { status: 500 }); } } [V0_FILE]typescript:file="app/api/mock/webhook/route.ts" import { NextResponse } from "next/server"; type Listener = { id: string; orderId: string; active: boolean; events: Array<{ type: string; amount?: number; response: string }>; }; declare global { var __paymentWebhooks: Map | undefined; } const store: Map = globalThis.__paymentWebhooks ?? (globalThis.__paymentWebhooks = new Map()); // Terminal events that settle the order and end the workflow const TERMINAL_EVENTS = new Set(["refund.created", "order.completed"]); export async function POST(request: Request) { let body: Record; try { body = await request.json(); } catch { return NextResponse.json( { error: "Invalid JSON body" }, { status: 400 } ); } // ── Start a new webhook listener ────────────────────────────────── if (!body.runId) { const orderId = typeof body.orderId === "string" && body.orderId ? body.orderId : `ord-${Date.now()}`; const id = `run_${crypto.randomUUID().slice(0, 8)}`; store.set(id, { id, orderId, active: true, events: [] }); return NextResponse.json({ runId: id, orderId }); } // ── Process an incoming payment event ───────────────────────────── const runId = String(body.runId); const listener = store.get(runId); if (!listener?.active) { return NextResponse.json( { error: "Webhook not found or settled" }, { status: 404 } ); } const type = typeof body.type === "string" ? body.type : "unknown"; const amount = typeof body.amount === "number" ? body.amount : undefined; let response = "Acknowledged"; if (type === "payment.created") response = "Payment received"; else if (type === "payment.requires_action") response = "Awaiting customer"; else if (type === "payment.succeeded") response = "Payment captured"; else if (type === "payment.failed") response = "Flagged for review"; else if (type === "refund.created") response = "Refund processed"; else if (type === "order.completed") response = "Order completed"; if (TERMINAL_EVENTS.has(type)) { listener.active = false; } listener.events.push({ type, amount, response }); return NextResponse.json({ type, response, settled: TERMINAL_EVENTS.has(type) }); } [V0_FILE]typescriptreact:file="app/page.tsx" import { highlight } from "sugar-high"; import { PaymentWebhookDemo } from "./components/demo"; // Split directive strings so withWorkflow() plugin doesn't scan them. const wf = `"use ${"workflow"}"`; const st = `"use ${"step"}"`; const orchestratorCode = `import { createWebhook } from "workflow"; export async function paymentWebhook(orderId: string) { ${wf}; const webhook = createWebhook({ token: \`order:\${orderId}\`, respondWith: "manual", }); const ledger: { type: string; amount?: number }[] = []; for await (const request of webhook) { const entry = await processPaymentEvent(request); ledger.push(entry); if (entry.type === "refund.created" || entry.type === "order.completed") break; } return { orderId, webhookUrl: webhook.url, ledger, status: "settled" }; }`; const stepCode = `import { type RequestWithResponse } from "workflow"; async function processPaymentEvent(request: RequestWithResponse) { ${st}; const body = await request.json().catch(() => ({})); const type = body?.type ?? "unknown"; const amount = typeof body?.amount === "number" ? body.amount : undefined; if (type === "payment.created") { await request.respondWith(Response.json({ ack: true, action: "received" })); return { type, amount, processedAt: new Date().toISOString() }; } if (type === "payment.requires_action") { await request.respondWith(Response.json({ ack: true, action: "awaiting customer" })); return { type, amount, processedAt: new Date().toISOString() }; } if (type === "payment.succeeded") { await request.respondWith(Response.json({ ack: true, action: "captured" })); return { type, amount, processedAt: new Date().toISOString() }; } if (type === "payment.failed") { await request.respondWith(Response.json({ ack: true, action: "flagged" })); return { type, amount, processedAt: new Date().toISOString() }; } if (type === "refund.created") { await request.respondWith(Response.json({ ack: true, action: "refunded" })); return { type, amount, processedAt: new Date().toISOString() }; } await request.respondWith(Response.json({ ack: true, action: "ignored" })); return { type, processedAt: new Date().toISOString() }; }`; // ── Pre-highlight on the server ─────────────────────────────────────── const orchestratorHtmlLines = highlight(orchestratorCode).split("\n"); const stepHtmlLines = highlight(stepCode).split("\n"); // ── Build line maps dynamically (never hardcode line numbers) ───────── function buildLineMap( code: string, markers: { marker: string; key: string; mode?: "line" | "block" }[] ): Record { const lines = code.split("\n"); const map: Record = {}; for (const { marker, key, mode } of markers) { for (let i = 0; i < lines.length; i++) { if (!lines[i].includes(marker)) continue; if (mode === "block") { const group = (map[key] ??= []); for (let j = i; j < lines.length; j++) { group.push(j + 1); if (j > i && lines[j].trim() === "}") break; } } else { (map[key] ??= []).push(i + 1); } break; } } return map; } // Orchestrator: createWebhook region needs special handling (multi-line call) function buildOrchestratorMap(code: string): Record { const lines = code.split("\n"); const map: Record = {}; // createWebhook region let inCreate = false; for (let i = 0; i < lines.length; i++) { if (lines[i].includes("createWebhook(")) inCreate = true; if (inCreate) { (map.connect ??= []).push(i + 1); if (lines[i].includes("});")) inCreate = false; } } // for-await loop lines for (let i = 0; i < lines.length; i++) { if (lines[i].includes("for await")) (map.loop ??= []).push(i + 1); if ( lines[i].includes("processPaymentEvent") && !lines[i].includes("async function") ) (map.loop ??= []).push(i + 1); if (lines[i].includes("ledger.push")) (map.loop ??= []).push(i + 1); } // break lines (terminal events + safety cap) for (let i = 0; i < lines.length; i++) { if (lines[i].includes("break;")) (map.breakLine ??= []).push(i + 1); if (lines[i].includes("return {") && lines[i].includes("orderId")) (map.returnResult ??= []).push(i + 1); } return map; } const orchestratorLineMap = buildOrchestratorMap(orchestratorCode); const stepLineMap = buildLineMap(stepCode, [ { marker: "request.json()", key: "parse" }, { marker: "body?.type", key: "parse" }, { marker: "body?.amount", key: "parse" }, { marker: '"payment.created"', key: "payment.created", mode: "block" }, { marker: '"payment.requires_action"', key: "payment.requires_action", mode: "block" }, { marker: '"payment.succeeded"', key: "payment.succeeded", mode: "block" }, { marker: '"payment.failed"', key: "payment.failed", mode: "block" }, { marker: '"refund.created"', key: "refund.created", mode: "block" }, ]); export default function Home() { return (

{/* ── Hero ───────────────────────────────────────────────── */}

Workflow DevKit Example

Payment Webhook

When a customer places an order, your workflow opens a durable webhook and tracks the payment lifecycle {"\u2014"} charges, failures, refunds {"\u2014"} inside a{" "} for await{" "} loop. It sleeps at{" "} zero compute between events, whether they arrive seconds or weeks apart.

{/* ── Demo + code (single integrated section) ──────────── */}

Try It

{/* ── Why this matters ────────────────────────────────────── */}

Why Not Just Use an Endpoint?

Traditional

Each webhook hit is a stateless HTTP handler. To track an order{"\u2019"}s payment lifecycle you need a database, a state machine, reconciliation logic, and cleanup jobs. The{" "} {"\u201C"}flow{"\u201D"} is scattered across handlers and DB rows.

Workflow Webhook

The for await loop{" "} expresses the state machine. Local variables like{" "} ledger persist across events without you managing a database. The workflow sleeps at zero compute between hits and the loop exits naturally when the payment settles.

In production, verify provider signatures (e.g. Stripe{"\u2019"}s{" "} Stripe-Signature) to prevent spoofed deliveries to the webhook URL.

{/* ── Footer ─────────────────────────────────────────────── */}

); } [V0_FILE]css:file="app/globals.css" @import "tailwindcss"; @theme { --color-background-100: #0a0a0a; --color-background-200: #171717; --color-gray-100: #1a1a1a; --color-gray-200: #1f1f1f; --color-gray-300: #292929; --color-gray-400: #737373; --color-gray-500: #525252; --color-gray-600: #404040; --color-gray-700: #262626; --color-gray-800: #171717; --color-gray-900: #a1a1a1; --color-gray-1000: #ededed; --color-blue-700: #0070f3; --color-red-700: #e5484d; --color-amber-700: #ffb224; --color-green-700: #46a758; --color-violet-700: #8b5cf6; --color-cyan-700: #06b6d4; --font-sans: var(--font-geist-sans); --font-mono: var(--font-geist-mono); } body { background: #0a0a0a; color: #ededed; font-family: var(--font-sans), -apple-system, BlinkMacSystemFont, sans-serif; } /* sugar-high syntax tokens */ :root, .dark { --sh-class: #52a8ff; --sh-identifier: #ededed; --sh-sign: #a1a1a1; --sh-property: #ff6166; --sh-entity: #62c073; --sh-jsxliterals: #ededed; --sh-string: #62c073; --sh-keyword: #f75f8f; --sh-comment: #a1a1a1; } [V0_FILE]javascript:file="postcss.config.mjs" const config = { plugins: { "@tailwindcss/postcss": {}, }, }; export default config; [V0_FILE]typescript:file="workflows/payment-webhook.ts" import { createWebhook, type RequestWithResponse } from "workflow"; const MAX_EVENTS = 50; export async function paymentWebhook(orderId: string) { "use workflow"; const webhook = createWebhook({ token: `order:${orderId}`, respondWith: "manual", }); const ledger: { type: string; amount?: number; processedAt: string }[] = []; for await (const request of webhook) { const entry = await processPaymentEvent(request); ledger.push(entry); if (entry.type === "refund.created" || entry.type === "order.completed") break; if (ledger.length >= MAX_EVENTS) break; } return { orderId, webhookUrl: webhook.url, ledger, status: "settled" as const }; } async function processPaymentEvent(request: RequestWithResponse) { "use step"; const body = await request.json().catch(() => ({})); const type = body?.type ?? "unknown"; const amount = typeof body?.amount === "number" ? body.amount : undefined; if (type === "payment.created") { await request.respondWith(Response.json({ ack: true, action: "received" })); return { type, amount, processedAt: new Date().toISOString() }; } if (type === "payment.requires_action") { await request.respondWith( Response.json({ ack: true, action: "awaiting customer" }) ); return { type, amount, processedAt: new Date().toISOString() }; } if (type === "payment.succeeded") { await request.respondWith(Response.json({ ack: true, action: "captured" })); return { type, amount, processedAt: new Date().toISOString() }; } if (type === "payment.failed") { await request.respondWith( Response.json({ ack: true, action: "flagged for review" }) ); return { type, amount, processedAt: new Date().toISOString() }; } if (type === "refund.created") { await request.respondWith( Response.json({ ack: true, action: "refunded" }) ); return { type, amount, processedAt: new Date().toISOString() }; } await request.respondWith(Response.json({ ack: true, action: "ignored" })); return { type, processedAt: new Date().toISOString() }; } [V0_FILE]json:file="package.json" { "name": "webhook-basics", "version": "0.1.0", "private": true, "scripts": { "dev": "next dev", "build": "next build", "start": "next start", "lint": "next lint" }, "dependencies": { "next": "16.0.10", "react": "19.2.3", "react-dom": "19.2.3", "sugar-high": "^0.9.5", "workflow": "4.1.0-beta.55" }, "devDependencies": { "@tailwindcss/postcss": "^4", "@types/node": "^20", "@types/react": "^19", "@types/react-dom": "^19", "tailwindcss": "^4", "typescript": "^5" } } [V0_FILE]json:file="tsconfig.json" { "compilerOptions": { "target": "ES2017", "lib": ["dom", "dom.iterable", "esnext"], "allowJs": true, "skipLibCheck": true, "strict": true, "noEmit": true, "esModuleInterop": true, "module": "esnext", "moduleResolution": "bundler", "resolveJsonModule": true, "isolatedModules": true, "jsx": "react-jsx", "incremental": true, "plugins": [{ "name": "next" }, { "name": "workflow" }], "baseUrl": ".", "paths": { "@/*": ["./*"] } }, "include": [ "next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts", ".next/dev/types/**/*.ts", "**/*.mts" ], "exclude": ["node_modules"] } [V0_FILE]typescript:file="next.config.ts" import { withWorkflow } from "workflow/next"; import type { NextConfig } from "next"; const nextConfig: NextConfig = {}; export default withWorkflow(nextConfig); [V0_FILE]yaml:file="pnpm-workspace.yaml" onlyBuiltDependencies: - '@nestjs/core' - '@swc/core' - cbor-extract - esbuild - sharp