Skip to content

webhook.mdx

Latest commit

 

History

History
111 lines (72 loc) · 3.97 KB

webhook.mdx

File metadata and controls

111 lines (72 loc) · 3.97 KB
Raw
title Webhook
description Webhook protocol schemas

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

Webhook Trigger Event

When should this webhook fire?

These mirror the record events the engine actually emits

(data.record.created / updated / deleted), which the webhook

auto-enqueuer maps to create / update / delete. Only events with a real

producer are declared here — an author can't subscribe to something that

never fires.

Deliberately NOT triggers (#3196):

  • undelete — there is no soft-delete / restore capability in the engine

(delete is a hard delete; no deleted_at convention, no restore

operation, no data.record.undeleted emit), so it had no event source.

Reintroduce it only alongside a real restore subsystem that emits an

undelete event.

  • api (manual/programmatic fire) — no manual fire path exists (the only

webhook HTTP surface re-queues already-failed deliveries). Reintroduce it

with a real "fire this webhook now" endpoint/service, not as a bare enum

value that silently never fires.

**Source:** `packages/spec/src/automation/webhook.zod.ts`

TypeScript Usage

import { Webhook, WebhookReceiver, WebhookTriggerType } from '@objectstack/spec/automation';
import type { Webhook, WebhookReceiver, WebhookTriggerType } from '@objectstack/spec/automation';

// Validate data
const result = Webhook.parse(data);

Webhook

Properties

Property Type Required Description
name string ✅ Webhook unique name (lowercase snake_case)
label string optional Human-readable webhook label
object string optional Object whose record events (create/update/delete) trigger this webhook
triggers Enum<'create' | 'update' | 'delete'>[] optional Events that trigger execution
url string ✅ External webhook endpoint URL
method Enum<'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'> ✅ HTTP method
headers Record<string, string> optional Custom HTTP headers
body any optional Request body payload (if not using default record data)
payloadFields string[] optional Fields to include. Empty = All
includeSession boolean ✅ Include user session info
authentication { type: Enum<'none' | 'bearer' | 'basic' | 'api-key'>; credentials?: Record<string, string> } optional Authentication configuration. [EXPERIMENTAL — not enforced] The webhook delivery path only applies HMAC signing via secret; bearer/basic/api-key credentials are not attached to outbound requests yet (liveness audit #1878/#1893).
retryPolicy { maxRetries: integer; backoffStrategy: Enum<'exponential' | 'linear' | 'fixed'>; initialDelayMs: integer; maxDelayMs: integer } optional Retry policy configuration
timeoutMs integer ✅ Request timeout in milliseconds
secret string optional Signing secret for HMAC signature verification
isActive boolean ✅ Whether webhook is active
description string optional Webhook description
tags string[] optional Tags for organization

WebhookReceiver

Properties

Property Type Required Description
name string ✅ Webhook receiver unique name (lowercase snake_case)
path string ✅ URL Path (e.g. /webhooks/stripe)
verificationType Enum<'none' | 'header_token' | 'hmac' | 'ip_whitelist'> ✅
verificationParams { header?: string; secret?: string; ips?: string[] } optional
action Enum<'trigger_flow' | 'script' | 'upsert_record'> ✅
target string ✅ Flow ID or Script name

WebhookTriggerType

Allowed Values

  • create
  • update
  • delete