khotan-dataalpha
View as Markdown
Webhooks

Catch

Catch a webhook event and write it to your Postgres. Verified signature, durable Vercel Workflow execution, automatic run tracking. Each catch handler is persisted to `khotan_webhook_handlers` and every execution creates a `khotan_runs` entry with the Workflow run ID for traceability. Tracked in the standard `khotan_runs` table — status, durations, batch counts, create/update/delete/fail tallies, plus a metadata JSON for component-specific stats. Toggle off with --no-runs.

stripe
signed
/api/hook
write
postgres

Install

terminal
$ npx khotan add catch <source>

Variants

A flow declares a variants map of named run modes, each with its own optional cron schedule and onError/onComplete hooks. The variant name is the mode — your flow code branches on ctx.variant. Click a tag above the preview to see the flow change. Select a variant when triggering:

ts
await khotanData.flow('catch').start({ variant: 'normal' })
terminal
$ npx khotan flows trigger catch normal

Variants with a schedule are dispatched independently by the cron dispatcher; variants without one are manual-only. Every run records its variant and source (scheduled | manual | webhook). What each variant actually does is up to your flow code and what the source API allows.

import { catchEvent, type CatchContext } from "./catch";
import { db } from "@/db";
import { webhookEvents } from "@/db/schema";
 
async function stripeCatchWorkflow(ctx: CatchContext) {
  "use workflow";
 
  async function persistEvent() {
    "use step";
    await db.insert(webhookEvents).values({
      source: "stripe",
      eventType: ctx.eventType,
      payload: ctx.event,
      receivedAt: new Date(),
    });
  }
 
  await persistEvent();
}
 
export const stripeCatch = catchEvent({
  name: "stripe-events",
  workflow: stripeCatchWorkflow,
});

Highlights

  • runs

What to expect from add

Running npx khotan add catch <source> scaffolds one or more files into your khotan runtime, React component directory, or app routes depending on the component. khotan may also prompt to install dependent components, npm packages, shadcn pieces, or Workflow integration when this component needs them.

Usage

Use the generated builder or UI inside your khotan setup and operational surfaces. For live runtime inspection, pair this component with the CLI and the built-in docs markdown routes.

Next steps