@pylonsync/webhooks 0.3.83

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@pylonsync/webhooks",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.3.83",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit",
+    "check": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@pylonsync/sdk": "0.3.81",
+    "@pylonsync/functions": "0.3.81"
+  },
+  "peerDependencies": {
+    "bun-types": "*"
+  },
+  "peerDependenciesMeta": {
+    "bun-types": {
+    "optional": true
+  }
+}
+}

package/src/dispatch.ts

@@ -0,0 +1,83 @@
+/**
+ * Dispatch path: app calls `dispatch(ctx, cfg, { type, data })`, the
+ * plugin finds every matching endpoint, schedules a delivery job
+ * for each.
+ *
+ * Jobs are scheduled via Pylon's `ctx.scheduler.runAfter(ms, fnName,
+ * args)` API — the framework's job worker picks them up + invokes
+ * the `_pylonWebhookDeliver` internal action.
+ *
+ * Caller's ctx.auth identity is propagated to the job (per v0.3.76
+ * fix), so the delivery handler executes with the same auth as the
+ * dispatcher — required because the worker reads the WebhookEndpoint
+ * + writes the WebhookAttempt under the same tenant scope.
+ */
+
+import type { DispatchInput, WebhookConfig, WebhookCtx } from "./types";
+
+export async function dispatch(
+	ctx: WebhookCtx,
+	cfg: WebhookConfig,
+	input: DispatchInput,
+): Promise<{ scheduled: number; eventId: string }> {
+	const eventId = input.id ?? generateEventId();
+	const occurredAt = input.occurredAt ?? new Date().toISOString();
+	const applicationId =
+		input.applicationId ??
+		(cfg.getApplicationId
+			? await cfg.getApplicationId(ctx, {
+					id: eventId,
+					type: input.type,
+					occurredAt,
+					data: input.data,
+				})
+			: ctx.auth.tenantId);
+	if (!applicationId) {
+		throw ctx.error(
+			"NO_APPLICATION",
+			"webhooks dispatch needs an applicationId (no active tenant)",
+		);
+	}
+
+	const endpoints = await ctx.runQuery<
+		Array<{
+			id: string;
+			url: string;
+			eventTypes: string;
+			disabled?: boolean;
+		}>
+	>("_pylonWebhookListEndpoints", { applicationId });
+
+	let scheduled = 0;
+	for (const ep of endpoints) {
+		if (ep.disabled) continue;
+		const types = safeParseArray(ep.eventTypes);
+		if (types.length > 0 && !types.includes(input.type)) continue;
+		await ctx.scheduler.runAfter(0, "_pylonWebhookDeliver", {
+			endpointId: ep.id,
+			eventId,
+			eventType: input.type,
+			occurredAt,
+			data: JSON.stringify(input.data),
+			applicationId,
+			attempt: 1,
+		});
+		scheduled++;
+	}
+	return { scheduled, eventId };
+}
+
+function generateEventId(): string {
+	const bytes = new Uint8Array(16);
+	crypto.getRandomValues(bytes);
+	return `evt_${[...bytes].map((b) => b.toString(16).padStart(2, "0")).join("")}`;
+}
+
+function safeParseArray(s: string): string[] {
+	try {
+		const out = JSON.parse(s);
+		return Array.isArray(out) ? (out as string[]) : [];
+	} catch {
+		return [];
+	}
+}

package/src/handlers.ts

@@ -0,0 +1,215 @@
+import { action, mutation, query, v } from "@pylonsync/functions";
+
+import { signWebhook } from "./signature";
+import type { WebhookConfig } from "./types";
+
+/**
+ * Plugin-internal handlers. Apps wrap these as one-line files in
+ * `functions/` (same pattern as @pylonsync/stripe).
+ *
+ * Public surface:
+ *   - none (dispatch is called from app code; delivery is server-
+ *     internal). Apps add their own typed `createWebhookEndpoint`
+ *     mutation that reads/writes the entity directly with whatever
+ *     authorization rules they want.
+ *
+ * Internal:
+ *   - _pylonWebhookListEndpoints — used by dispatch()
+ *   - _pylonWebhookDeliver       — the worker job
+ *   - _pylonWebhookRecordAttempt — write the audit row
+ */
+export function internalHandlers(
+	cfg: WebhookConfig,
+): Record<string, unknown> {
+	const endpointEnt = cfg.entities?.endpoint ?? "WebhookEndpoint";
+	const attemptEnt = cfg.entities?.attempt ?? "WebhookAttempt";
+	const retrySchedule = cfg.retrySchedule ?? [];
+
+	return {
+		_pylonWebhookListEndpoints: query({
+			args: { applicationId: v.string() },
+			internal: true,
+			async handler(ctx, args: { applicationId: string }) {
+				return ctx.db.query(endpointEnt, {
+					applicationId: args.applicationId,
+				});
+			},
+		}),
+
+		_pylonWebhookRecordAttempt: mutation({
+			args: {
+				applicationId: v.string(),
+				endpointId: v.string(),
+				eventId: v.string(),
+				eventType: v.string(),
+				url: v.string(),
+				attempt: v.number(),
+				status: v.string(),
+				httpStatus: v.optional(v.number()),
+				error: v.optional(v.string()),
+				scheduledAt: v.string(),
+				deliveredAt: v.optional(v.string()),
+			},
+			internal: true,
+			async handler(
+				ctx,
+				args: {
+					applicationId: string;
+					endpointId: string;
+					eventId: string;
+					eventType: string;
+					url: string;
+					attempt: number;
+					status: string;
+					httpStatus?: number;
+					error?: string;
+					scheduledAt: string;
+					deliveredAt?: string;
+				},
+			) {
+				return ctx.db.insert(attemptEnt, {
+					applicationId: args.applicationId,
+					endpointId: args.endpointId,
+					eventId: args.eventId,
+					eventType: args.eventType,
+					url: args.url,
+					attempt: args.attempt,
+					status: args.status,
+					httpStatus: args.httpStatus ?? null,
+					error: args.error ?? null,
+					scheduledAt: args.scheduledAt,
+					deliveredAt: args.deliveredAt ?? null,
+				});
+			},
+		}),
+
+		_pylonWebhookDeliver: action({
+			args: {
+				endpointId: v.string(),
+				eventId: v.string(),
+				eventType: v.string(),
+				occurredAt: v.string(),
+				data: v.string(),
+				applicationId: v.string(),
+				attempt: v.number(),
+			},
+			internal: true,
+			async handler(
+				ctx,
+				args: {
+					endpointId: string;
+					eventId: string;
+					eventType: string;
+					occurredAt: string;
+					data: string;
+					applicationId: string;
+					attempt: number;
+				},
+			) {
+				const endpoints = await ctx.runQuery<
+					Array<{
+						id: string;
+						url: string;
+						secret: string;
+						disabled?: boolean;
+						headers?: string | null;
+					}>
+				>("_pylonWebhookListEndpoints", {
+					applicationId: args.applicationId,
+				});
+				const ep = endpoints.find((e) => e.id === args.endpointId);
+				if (!ep || ep.disabled) {
+					return { skipped: true };
+				}
+
+				const payload = JSON.parse(args.data) as unknown;
+				const body = JSON.stringify({
+					id: args.eventId,
+					type: args.eventType,
+					occurredAt: args.occurredAt,
+					data: payload,
+				});
+				const ts = Math.floor(Date.now() / 1000);
+				const sig = await signWebhook({
+					id: args.eventId,
+					timestamp: ts,
+					body,
+					secrets: [ep.secret],
+				});
+
+				const headers: Record<string, string> = {
+					"Content-Type": "application/json",
+					"webhook-id": sig.id,
+					"webhook-timestamp": String(sig.timestamp),
+					"webhook-signature": sig.signature,
+				};
+				if (ep.headers) {
+					try {
+						const extra = JSON.parse(ep.headers) as Record<string, string>;
+						for (const [k, v] of Object.entries(extra)) headers[k] = v;
+					} catch {
+						/* malformed headers — ignore */
+					}
+				}
+
+				let httpStatus = 0;
+				let errorMsg: string | undefined;
+				let ok = false;
+				try {
+					const res = await fetch(ep.url, {
+						method: "POST",
+						headers,
+						body,
+					});
+					httpStatus = res.status;
+					ok = res.ok;
+					if (!ok) errorMsg = `HTTP ${res.status}`;
+				} catch (e) {
+					errorMsg = e instanceof Error ? e.message : String(e);
+				}
+
+				const now = new Date().toISOString();
+				await ctx.runMutation("_pylonWebhookRecordAttempt", {
+					applicationId: args.applicationId,
+					endpointId: ep.id,
+					eventId: args.eventId,
+					eventType: args.eventType,
+					url: ep.url,
+					attempt: args.attempt,
+					status: ok ? "succeeded" : "failed",
+					httpStatus,
+					error: errorMsg,
+					scheduledAt: now,
+					deliveredAt: ok ? now : undefined,
+				});
+
+				if (!ok) {
+					const nextOffset = retrySchedule[args.attempt - 1];
+					if (nextOffset === undefined) {
+						// Out of retries — write a `dead` row + bail.
+						await ctx.runMutation("_pylonWebhookRecordAttempt", {
+							applicationId: args.applicationId,
+							endpointId: ep.id,
+							eventId: args.eventId,
+							eventType: args.eventType,
+							url: ep.url,
+							attempt: args.attempt + 1,
+							status: "dead",
+							httpStatus,
+							error: errorMsg,
+							scheduledAt: now,
+						});
+						return { delivered: false, dead: true };
+					}
+					await ctx.scheduler.runAfter(
+						nextOffset * 1000,
+						"_pylonWebhookDeliver",
+						{ ...args, attempt: args.attempt + 1 },
+					);
+					return { delivered: false, retryIn: nextOffset };
+				}
+				return { delivered: true, httpStatus };
+			},
+		}),
+	};
+}

package/src/index.ts

@@ -0,0 +1,77 @@
+/**
+ * `@pylonsync/webhooks` — outbound webhook delivery.
+ *
+ * Three primitives:
+ *   - `signWebhook`/`verifyWebhook` — Svix-compatible HMAC-SHA256
+ *     signature with timestamp + replay window. Receivers using
+ *     Svix's reference verifier (Clerk, Resend, anyone with a
+ *     `whsec_*` secret) work unchanged.
+ *   - `dispatch(ctx, cfg, { type, data })` — fan out an event to
+ *     every endpoint subscribed to `type`. Enqueues delivery jobs
+ *     via `ctx.scheduler.runAfter`.
+ *   - `deliverNow(ctx, cfg, attemptId)` — the worker side. Signs
+ *     and POSTs, re-enqueues on failure with the next retry interval.
+ *
+ * Manifest fragment adds two entities:
+ *   - `WebhookEndpoint` — customer-registered URLs
+ *   - `WebhookAttempt`  — delivery audit log (one row per attempt)
+ *
+ * Schema is intentionally minimal: apps that want richer
+ * application/event-type catalogs (Svix's full model) layer that on
+ * top, the plugin doesn't enforce a structure.
+ */
+
+export { signWebhook, verifyWebhook } from "./signature";
+export type {
+	SignOptions,
+	WebhookSignaturePayload,
+	SignatureError,
+} from "./signature";
+export type {
+	WebhookEvent,
+	WebhookEndpoint,
+	WebhookConfig,
+	WebhookCtx,
+	DispatchInput,
+	DeliveryAttempt,
+} from "./types";
+
+import { buildWebhookManifest, type WebhookManifestFragment } from "./manifest";
+import { dispatch } from "./dispatch";
+import { internalHandlers } from "./handlers";
+import type { WebhookConfig } from "./types";
+
+export { buildWebhookManifest } from "./manifest";
+export type { WebhookManifestFragment } from "./manifest";
+export { dispatch } from "./dispatch";
+
+export const DEFAULT_RETRY_SCHEDULE_SECS = [
+	5, // 5s
+	300, // 5m
+	1800, // 30m
+	7200, // 2h
+	18000, // 5h
+	36000, // 10h
+	50400, // 14h
+];
+
+export interface WebhooksPlugin {
+	config: WebhookConfig;
+	manifest: WebhookManifestFragment;
+	handlers: Record<string, unknown>;
+	dispatch: typeof dispatch;
+}
+
+export function webhooks(cfg: WebhookConfig = {}): WebhooksPlugin {
+	const resolved: WebhookConfig = {
+		retrySchedule: cfg.retrySchedule ?? DEFAULT_RETRY_SCHEDULE_SECS,
+		replayToleranceSecs: cfg.replayToleranceSecs ?? 300,
+		...cfg,
+	};
+	return {
+		config: resolved,
+		manifest: buildWebhookManifest(resolved),
+		handlers: internalHandlers(resolved),
+		dispatch,
+	};
+}

package/src/manifest.ts

@@ -0,0 +1,78 @@
+import {
+	type EntityDefinition,
+	type PolicyDefinition,
+	entity,
+	field,
+	policy,
+} from "@pylonsync/sdk";
+
+import type { WebhookConfig } from "./types";
+
+export interface WebhookManifestFragment {
+	entities: EntityDefinition[];
+	policies: PolicyDefinition[];
+}
+
+export function buildWebhookManifest(
+	cfg: WebhookConfig,
+): WebhookManifestFragment {
+	const endpointName = cfg.entities?.endpoint ?? "WebhookEndpoint";
+	const attemptName = cfg.entities?.attempt ?? "WebhookAttempt";
+
+	const Endpoint = entity(endpointName, {
+		applicationId: field.string(),
+		url: field.string(),
+		secret: field.string(),
+		eventTypes: field.string(), // JSON array
+		headers: field.string().optional(), // JSON
+		disabled: field.boolean().optional(),
+		createdAt: field.string(),
+	});
+
+	const Attempt = entity(attemptName, {
+		applicationId: field.string(),
+		endpointId: field.string(),
+		eventId: field.string(),
+		eventType: field.string(),
+		url: field.string(),
+		attempt: field.number(),
+		status: field.string(),
+		httpStatus: field.number().optional(),
+		error: field.string().optional(),
+		scheduledAt: field.string(),
+		deliveredAt: field.string().optional(),
+	});
+
+	// Endpoints are tenant-scoped (app == tenant in the common
+	// multi-tenant SaaS case). Apps that want admin-only access
+	// override these in their own manifest.
+	const endpointPolicy = policy({
+		name: `${endpointName.toLowerCase()}_tenant_scoped`,
+		entity: endpointName,
+		allowRead: "auth.tenantId == data.applicationId or auth.is_admin == true",
+		allowInsert:
+			"auth.tenantId == data.applicationId or auth.is_admin == true",
+		allowUpdate:
+			"auth.tenantId == data.applicationId or auth.is_admin == true",
+		allowDelete:
+			"auth.tenantId == data.applicationId or auth.is_admin == true",
+	});
+
+	// Attempt rows are read-only — they're an internal audit trail.
+	// Tenant-scoped reads so the customer's dashboard can show
+	// delivery history; writes only via the plugin's internal
+	// mutation.
+	const attemptPolicy = policy({
+		name: `${attemptName.toLowerCase()}_read_only`,
+		entity: attemptName,
+		allowRead: "auth.tenantId == data.applicationId or auth.is_admin == true",
+		allowInsert: "false",
+		allowUpdate: "false",
+		allowDelete: "false",
+	});
+
+	return {
+		entities: [Endpoint, Attempt],
+		policies: [endpointPolicy, attemptPolicy],
+	};
+}

package/src/signature.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, test } from "bun:test";
+
+import { signWebhook, verifyWebhook } from "./signature";
+
+const SECRET = "whsec_dGVzdC1zZWNyZXQtdmFsdWU="; // base64('test-secret-value')
+const ID = "evt_test_123";
+const BODY = '{"id":"evt_test_123","type":"x.y","data":{}}';
+
+describe("webhook signature", () => {
+	test("sign + verify round-trip succeeds", async () => {
+		const ts = 1_700_000_000;
+		const sig = await signWebhook({
+			id: ID,
+			timestamp: ts,
+			body: BODY,
+			secrets: [SECRET],
+		});
+		const result = await verifyWebhook(
+			SECRET,
+			{ id: sig.id, timestamp: String(sig.timestamp), signature: sig.signature },
+			BODY,
+			{ nowSecs: ts },
+		);
+		expect(result).toBe(true);
+	});
+
+	test("verify rejects a stale timestamp (replay window)", async () => {
+		const ts = 1_700_000_000;
+		const sig = await signWebhook({
+			id: ID,
+			timestamp: ts,
+			body: BODY,
+			secrets: [SECRET],
+		});
+		const result = await verifyWebhook(
+			SECRET,
+			{ id: sig.id, timestamp: String(sig.timestamp), signature: sig.signature },
+			BODY,
+			{ nowSecs: ts + 10 * 60 }, // 10 min later
+		);
+		expect(result).toBe("REPLAYED");
+	});
+
+	test("verify rejects a tampered body", async () => {
+		const ts = 1_700_000_000;
+		const sig = await signWebhook({
+			id: ID,
+			timestamp: ts,
+			body: BODY,
+			secrets: [SECRET],
+		});
+		const result = await verifyWebhook(
+			SECRET,
+			{ id: sig.id, timestamp: String(sig.timestamp), signature: sig.signature },
+			`${BODY}x`, // tampered
+			{ nowSecs: ts },
+		);
+		expect(result).toBe("INVALID_SIGNATURE");
+	});
+
+	test("verify accepts either signature during rotation", async () => {
+		const ts = 1_700_000_000;
+		const oldSecret = "whsec_b2xkLXNlY3JldA=="; // base64('old-secret')
+		const sig = await signWebhook({
+			id: ID,
+			timestamp: ts,
+			body: BODY,
+			secrets: [oldSecret, SECRET], // old + new
+		});
+		// Receiver using only the new secret still accepts.
+		expect(
+			await verifyWebhook(
+				SECRET,
+				{ id: sig.id, timestamp: String(sig.timestamp), signature: sig.signature },
+				BODY,
+				{ nowSecs: ts },
+			),
+		).toBe(true);
+		// Receiver still on the old secret also accepts.
+		expect(
+			await verifyWebhook(
+				oldSecret,
+				{ id: sig.id, timestamp: String(sig.timestamp), signature: sig.signature },
+				BODY,
+				{ nowSecs: ts },
+			),
+		).toBe(true);
+	});
+
+	test("verify reports missing headers", async () => {
+		expect(
+			await verifyWebhook(SECRET, { id: null, timestamp: "1", signature: "v1,x" }, BODY),
+		).toBe("MISSING_ID");
+		expect(
+			await verifyWebhook(SECRET, { id: "x", timestamp: null, signature: "v1,x" }, BODY),
+		).toBe("MISSING_TIMESTAMP");
+		expect(
+			await verifyWebhook(SECRET, { id: "x", timestamp: "1", signature: null }, BODY),
+		).toBe("MISSING_SIGNATURE");
+	});
+});

package/src/signature.ts

@@ -0,0 +1,136 @@
+/**
+ * Svix-compatible HMAC-SHA256 signing for outbound webhooks.
+ *
+ * Headers we attach:
+ *   - `webhook-id`: stable event id (used by receivers for dedup)
+ *   - `webhook-timestamp`: unix seconds
+ *   - `webhook-signature`: `v1,<base64-sig> [v1,<base64-sig-2>...]`
+ *     Multiple v1s appear during secret rotation — both old and new
+ *     secrets are signed simultaneously for a configurable overlap
+ *     window so receivers can update their secret without dropping
+ *     deliveries.
+ *
+ * Signature input: `<webhook-id>.<webhook-timestamp>.<body>`
+ *
+ * Conformant with the Svix signature spec so existing receivers
+ * (Resend, Clerk, anyone using their reference verifier) work
+ * unchanged.
+ */
+
+export interface SignOptions {
+	id: string;
+	timestamp: number;
+	body: string;
+	secrets: string[];
+}
+
+export interface WebhookSignaturePayload {
+	id: string;
+	timestamp: number;
+	signature: string;
+}
+
+export async function signWebhook(
+	opts: SignOptions,
+): Promise<WebhookSignaturePayload> {
+	const sigs: string[] = [];
+	for (const secret of opts.secrets) {
+		const sig = await hmacSha256B64(
+			normalizeSecret(secret),
+			`${opts.id}.${opts.timestamp}.${opts.body}`,
+		);
+		sigs.push(`v1,${sig}`);
+	}
+	return {
+		id: opts.id,
+		timestamp: opts.timestamp,
+		signature: sigs.join(" "),
+	};
+}
+
+export type SignatureError =
+	| "MISSING_ID"
+	| "MISSING_TIMESTAMP"
+	| "MISSING_SIGNATURE"
+	| "REPLAYED"
+	| "INVALID_SIGNATURE";
+
+export async function verifyWebhook(
+	secret: string,
+	headers: {
+		id?: string | null;
+		timestamp?: string | null;
+		signature?: string | null;
+	},
+	body: string,
+	opts: { toleranceSecs?: number; nowSecs?: number } = {},
+): Promise<true | SignatureError> {
+	const id = headers.id;
+	const ts = headers.timestamp;
+	const sig = headers.signature;
+	if (!id) return "MISSING_ID";
+	if (!ts) return "MISSING_TIMESTAMP";
+	if (!sig) return "MISSING_SIGNATURE";
+
+	const tsNum = Number.parseInt(ts, 10);
+	if (Number.isNaN(tsNum)) return "MISSING_TIMESTAMP";
+	const now = opts.nowSecs ?? Math.floor(Date.now() / 1000);
+	const tolerance = opts.toleranceSecs ?? 300;
+	if (Math.abs(now - tsNum) > tolerance) return "REPLAYED";
+
+	const expected = await hmacSha256B64(
+		normalizeSecret(secret),
+		`${id}.${ts}.${body}`,
+	);
+	for (const part of sig.split(" ")) {
+		const [version, candidate] = part.split(",");
+		if (version !== "v1") continue;
+		if (constantTimeEqual(candidate, expected)) return true;
+	}
+	return "INVALID_SIGNATURE";
+}
+
+function normalizeSecret(secret: string): Uint8Array {
+	if (secret.startsWith("whsec_")) {
+		return base64Decode(secret.slice("whsec_".length));
+	}
+	return new TextEncoder().encode(secret);
+}
+
+async function hmacSha256B64(
+	secret: Uint8Array,
+	payload: string,
+): Promise<string> {
+	const secretBuf = new ArrayBuffer(secret.byteLength);
+	new Uint8Array(secretBuf).set(secret);
+	const bodyBytes = new TextEncoder().encode(payload);
+	const bodyBuf = new ArrayBuffer(bodyBytes.byteLength);
+	new Uint8Array(bodyBuf).set(bodyBytes);
+	const key = await crypto.subtle.importKey(
+		"raw",
+		secretBuf,
+		{ name: "HMAC", hash: "SHA-256" },
+		false,
+		["sign"],
+	);
+	const sig = await crypto.subtle.sign("HMAC", key, bodyBuf);
+	return base64Encode(new Uint8Array(sig));
+}
+
+function base64Decode(s: string): Uint8Array {
+	const bin = atob(s);
+	const out = new Uint8Array(bin.length);
+	for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+	return out;
+}
+function base64Encode(bytes: Uint8Array): string {
+	let s = "";
+	for (const b of bytes) s += String.fromCharCode(b);
+	return btoa(s);
+}
+function constantTimeEqual(a: string, b: string): boolean {
+	if (a.length !== b.length) return false;
+	let diff = 0;
+	for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+	return diff === 0;
+}

package/src/types.ts

@@ -0,0 +1,119 @@
+/**
+ * `@pylonsync/webhooks` — outbound webhook delivery for Pylon apps.
+ *
+ * Svix-style HMAC-SHA256 signed payloads with timestamp +
+ * replay-window protection, exponential-backoff retry schedule,
+ * secret rotation overlap, per-endpoint event filtering,
+ * idempotent delivery via stable event ids.
+ *
+ * Mental model:
+ *   - Apps register **endpoints** at runtime: customer-supplied
+ *     URLs that should receive certain event types.
+ *   - The app's domain code calls `dispatch(ctx, { type, payload })`
+ *     when something happens.
+ *   - The plugin enqueues delivery to each matching endpoint via
+ *     Pylon's job queue.
+ *   - Worker pulls the job, signs the payload with the endpoint's
+ *     secret, POSTs it. On failure, re-enqueues with the next
+ *     retry interval (5s → 5m → 30m → 2h → 5h → 10h → 14h → dead).
+ */
+
+export interface WebhookEvent<T = unknown> {
+	/** Stable id. Receivers dedup on this. */
+	id: string;
+	type: string;
+	occurredAt: string;
+	data: T;
+}
+
+export interface WebhookEndpoint {
+	id: string;
+	/** Logical bucket — usually the customer/org id. */
+	applicationId: string;
+	url: string;
+	/** Hex-encoded HMAC secret. Plaintext on the row by design — only
+	 *  the customer's app reads + uses it, and Pylon's at-rest crypto
+	 *  is the secret-encryption layer apps wire when they want it. */
+	secret: string;
+	/** Subset of event types this endpoint subscribes to. Empty = all. */
+	eventTypes: string[];
+	/**
+	 * Headers to attach on every delivery. Useful for routing /
+	 * authentication beyond the HMAC signature.
+	 */
+	headers?: Record<string, string>;
+	/** Disabled endpoints don't receive deliveries. */
+	disabled?: boolean;
+	createdAt: string;
+}
+
+export interface WebhookConfig {
+	entities?: {
+		endpoint?: string;
+		attempt?: string;
+	};
+	/**
+	 * Retry schedule (seconds offset from initial attempt). Default
+	 * matches Svix's published schedule. After exhausting the
+	 * schedule, the attempt is marked `dead` and the destination
+	 * goes to the dead-letter queue.
+	 */
+	retrySchedule?: number[];
+	/** Replay window for signature validation. Default 300s. */
+	replayToleranceSecs?: number;
+	/**
+	 * App identifier resolver. For multi-tenant apps, this returns
+	 * the application id (org id) from the dispatch context — used
+	 * to filter endpoints to the right customer.
+	 */
+	getApplicationId?: (
+		ctx: WebhookCtx,
+		payload: WebhookEvent,
+	) => string | null | Promise<string | null>;
+}
+
+export interface WebhookCtx {
+	env: Record<string, string | undefined>;
+	auth: { userId?: string | null; tenantId?: string | null };
+	runQuery: <T>(name: string, args: Record<string, unknown>) => Promise<T>;
+	runMutation: <T = unknown>(
+		name: string,
+		args: Record<string, unknown>,
+	) => Promise<T>;
+	scheduler: {
+		runAfter: (
+			ms: number,
+			fn: string,
+			args: Record<string, unknown>,
+		) => Promise<string>;
+	};
+	error: (code: string, message: string) => Error;
+}
+
+export interface DispatchInput {
+	type: string;
+	data: unknown;
+	/**
+	 * Stable event id. Apps that produce events idempotently (e.g.
+	 * "subscription.updated" from a Stripe webhook) should pass
+	 * the upstream event id here so re-deliveries dedup. Auto-
+	 * generated when absent.
+	 */
+	id?: string;
+	/** Override the auto-resolved application id. */
+	applicationId?: string;
+	occurredAt?: string;
+}
+
+export interface DeliveryAttempt {
+	id: string;
+	eventId: string;
+	endpointId: string;
+	url: string;
+	attempt: number;
+	status: "pending" | "succeeded" | "failed" | "dead";
+	httpStatus?: number;
+	error?: string;
+	scheduledAt: string;
+	deliveredAt?: string;
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "types": ["bun-types"]
+  },
+  "include": [
+    "src"
+  ]
+}