Webhooks

Preview

Install

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/webhooks

Brings in: alert-dialog, bidi, button, checkbox, data, heading-level, heading-scope, input, locale, locked, page-state, relative-time, switch, tokens, utils · npm: lucide-react@^1.67.0

Usage

"use client"

import * as React from "react"
import { Webhooks, type Webhook } from "@/components/candor/webhooks"

const ago = (m: number) => new Date(Date.now() - m * 60_000).toISOString()
const events = [
  { id: "run.finished", label: "Run finished" },
  { id: "run.failed", label: "Run failed" },
  { id: "approval.requested", label: "Approval requested", description: "An agent is waiting on a person" },
]

export default function Example() {
  const [hooks, setHooks] = React.useState<Webhook[]>([
    {
      id: "w1",
      url: "https://ops.example.com/hooks/agents",
      events: ["run.failed", "approval.requested"],
      enabled: true,
      deliveries: [
        { id: "d2", event: "run.failed", at: ago(12), outcome: "delivered", status: 200, durationMs: 142 },
        { id: "d1", event: "approval.requested", at: ago(95), outcome: "failed", status: 503, durationMs: 10_000, error: "Timed out after 10 s" },
      ],
    },
  ])
  return (
    <Webhooks
      className="max-w-xl"
      webhooks={hooks}
      events={events}
      onAdd={(url, chosen) => setHooks((h) => [...h, { id: url, url, events: chosen, enabled: true, deliveries: [] }])}
      onToggle={(id, enabled) => setHooks((h) => h.map((x) => (x.id === id ? { ...x, enabled } : x)))}
      onTest={async () => {
        await new Promise((r) => setTimeout(r, 500))
        return { id: "test", event: "run.finished", at: new Date().toISOString(), outcome: "delivered", status: 200, durationMs: 98 }
      }}
      onRemove={(id) => setHooks((h) => h.filter((x) => x.id !== id))}
    />
  )
}

<Webhooks>

Strings

Types

WebhookDelivery

One attempt to deliver an event to an endpoint, as the app recorded it.

{ id: string; /** The event's id from `events`. */ event: string; at: string; outcome: "delivered" | "failed" | "pending"; /** The HTTP status the endpoint answered with, when it answered. */ status?: number | undefined; /** How long the endpoint took to answer, in ms, as measured by the app. */ durationMs?: number | undefined; /** Why it failed, in the app's words ("Timed out after 10 s"). */ error?: string | undefined; }

Webhook

An endpoint the app sends events to.

{ id: string; url: string; /** * How the endpoint reads on screen, in its labels and in the remove dialog, in place of `url`: "Slack #deploys", * "hooks.slack.com/…/B07". Set it when the URL carries a secret, as Slack and Discord webhook URLs do, so the token * isn't shown or read aloud. Left out, the URL is. */ label?: string | undefined; /** Event ids from `events`. */ events: string[]; /** Whether events are sent to it now. */ enabled: boolean; /** The latest deliveries, newest first. Leave it out when the app doesn't keep them. */ deliveries?: WebhookDelivery[] | undefined; }

WebhookEvent

An event an endpoint can subscribe to.

{ id: string; /** What happened, e.g. "Run finished". */ label: string; description?: string | undefined; }

Types from other items

The props above take these. Each is defined by another item; import it from the path shown.

ListState from @/lib/candor/data

What a list or table is showing, the same shape as `ChartState` and as page-state's `ListState` (which the free tier ships, so it declares its own rather than import this file): its rows (ready), the shape of rows still coming (loading), nothing and why (empty), the rows it has with a note on what's missing (partial), or why it couldn't load (error). Lists without a `state` show their rows.

ChartState

HeadingLevel from @/lib/candor/heading-level

A heading's level in the page's outline: `1` is `<h1>`, `6` is `<h6>`. Every Candor item that draws a heading takes its `headingLevel` as this type; the level is where the heading sits in the outline, never how large it looks.

1 | 2 | 3 | 4 | 5 | 6

ChartState from @/lib/candor/data

{ kind: "ready"; } | { kind: "loading"; } /** Nothing to plot, and why. */ | { kind: "empty"; reason: string; } /** Some of the range is missing. */ | { kind: "partial"; note: string; } | { kind: "error"; reason: string; }