@hogsend/engine 0.8.0 → 0.9.0

package/src/destinations/registry-singleton.ts

@@ -0,0 +1,78 @@
+import type { DefinedDestination } from "./define-destination.js";
+import { PRESET_DESTINATIONS } from "./presets/index.js";
+
+/**
+ * The process-wide destination registry, set once by `createHogsendClient` at
+ * startup and read by the delivery task (`workflows/deliver-webhook.ts`) to
+ * resolve a transform by `endpoint.kind`.
+ *
+ * Why a singleton (mirrors `lib/analytics-singleton.ts`): the durable
+ * `deliverWebhookTask` SELF-BOOTS — it opens its own `getDb()` from
+ * `process.env` and has NO client/container reference. So the registered
+ * transforms (presets + the consumer's `defineDestination()` destinations) MUST
+ * be reachable via a process singleton, exactly as analytics / the journey +
+ * bucket registries are. `createHogsendClient` runs in BOTH the API and worker,
+ * so by the time any worker task executes the registry has been installed.
+ *
+ * Resilient default: if a delivery task somehow runs in a process that never
+ * called `createHogsendClient` (a bare reaper re-drive in a test harness), the
+ * getter lazily falls back to the shipped {@link PRESET_DESTINATIONS} so the
+ * no-regression `webhook` + the `posthog` presets still resolve. Installing a
+ * registry via {@link setDestinationRegistry} replaces this fallback.
+ */
+export class DestinationRegistry {
+  private readonly byKind = new Map<string, DefinedDestination>();
+
+  constructor(destinations: DefinedDestination[] = []) {
+    for (const destination of destinations) {
+      // Last-writer-wins on id collision — the caller (container) orders the
+      // array so the consumer's destination wins over a preset of the same id.
+      this.byKind.set(destination.meta.id, destination);
+    }
+  }
+
+  /** Resolve a destination by its `kind` id, or `undefined` when unregistered. */
+  get(kind: string): DefinedDestination | undefined {
+    return this.byKind.get(kind);
+  }
+
+  /** Every registered destination (for diagnostics / catalog enumeration). */
+  getAll(): DefinedDestination[] {
+    return [...this.byKind.values()];
+  }
+
+  /** Number of registered destinations. */
+  count(): number {
+    return this.byKind.size;
+  }
+}
+
+/** The lazily-built fallback registry of just the shipped presets. */
+let fallback: DestinationRegistry | undefined;
+let installed: DestinationRegistry | undefined;
+
+/**
+ * Install the resolved destination registry. Called by `createHogsendClient`
+ * after merging the env presets with the consumer's `opts.destinations`.
+ */
+export function setDestinationRegistry(registry: DestinationRegistry): void {
+  installed = registry;
+}
+
+/**
+ * Read the destination registry. Returns the installed registry, or a lazily
+ * built preset-only fallback so a self-booting task always resolves the
+ * always-on `webhook` + `posthog` presets even before any container ran.
+ */
+export function getDestinationRegistry(): DestinationRegistry {
+  if (installed) return installed;
+  if (!fallback) {
+    fallback = new DestinationRegistry(Object.values(PRESET_DESTINATIONS));
+  }
+  return fallback;
+}
+
+/** Reset the installed registry — only for test cleanup. */
+export function resetDestinationRegistry(): void {
+  installed = undefined;
+}

package/src/env.ts

@@ -57,6 +57,12 @@ export const env = createEnv({
     POSTHOG_API_KEY: z.string().min(1).optional(),
     POSTHOG_HOST: z.string().url().optional(),
     POSTHOG_WEBHOOK_SECRET: z.string().min(1).optional(),
+    // When true AND POSTHOG_API_KEY is set, the engine idempotently auto-seeds
+    // ONE kind="posthog" webhook endpoint subscribed to the email funnel so the
+    // full email lifecycle fans out to PostHog DURABLY (on the delivery spine).
+    // Default OFF to avoid a surprise double-emit alongside the existing
+    // fire-and-forget PostHog capture path.
+    ENABLE_POSTHOG_DESTINATION: z.coerce.boolean().default(false),
     RESEND_WEBHOOK_SECRET: z.string().min(1).optional(),
     ADMIN_API_KEY: z.string().min(1).optional(),
     API_PUBLIC_URL: z.string().url().default("http://localhost:3002"),
@@ -96,6 +102,15 @@ export const env = createEnv({
     // Preset enablement override: csv of preset ids, `"*"` (all with a secret),
     // or `"none"`. Absent → auto-enable any preset whose secret is set.
     ENABLED_WEBHOOK_PRESETS: z.string().optional(),
+    // --- Outbound destination presets (Phase 3) ---
+    // Which `defineDestination()` PRESETS are registered into the process
+    // destination registry the delivery task resolves by `endpoint.kind`. csv of
+    // ids (e.g. "segment,slack"), `"*"` (all presets), or `"none"`. Absent → the
+    // DEFAULT set (webhook + posthog). The `webhook` and `posthog` presets are
+    // ALWAYS registered regardless of this value, so the no-regression delivery
+    // path can never be turned off by misconfiguration. Set this to add the
+    // segment/slack presets (credentials still live per-endpoint in `config`).
+    ENABLED_DESTINATION_PRESETS: z.string().optional(),
   },
   runtimeEnv: process.env,
   emptyStringAsUndefined: true,

package/src/index.ts

@@ -76,6 +76,31 @@ export {
   type HogsendClientOptions,
   type HogsendDefaults,
 } from "./container.js";
+// --- Outbound destinations: public authoring layer (Phase 3) ---
+export {
+  type DefinedDestination,
+  type DestinationCtx,
+  type DestinationEnvelope,
+  type DestinationMeta,
+  type DestinationTransformResult,
+  defineDestination,
+  type WebhookEndpointRow,
+} from "./destinations/define-destination.js";
+export {
+  type DestinationPresetId,
+  destinationsFromEnv,
+  PRESET_DESTINATIONS,
+  posthogDestination,
+  segmentDestination,
+  slackDestination,
+  webhookDestination,
+} from "./destinations/presets/index.js";
+export {
+  DestinationRegistry,
+  getDestinationRegistry,
+  resetDestinationRegistry,
+  setDestinationRegistry,
+} from "./destinations/registry-singleton.js";
 // --- Env ---
 export { API_VERSION, env } from "./env.js";
 // --- Journeys ---

package/src/journeys/define-journey.ts

@@ -179,7 +179,6 @@ export function defineJourney(options: {
         hatchetCtx,
         registry: getJourneyRegistrySingleton(),
         logger,
-        posthog,
         stateId,
         userId,
         userEmail,

package/src/journeys/journey-context.ts

@@ -7,7 +7,7 @@ import {
   SleepCondition,
   UserEventCondition,
 } from "@hatchet-dev/typescript-sdk/v1/index.js";
-import type { DurationObject, PostHogService } from "@hogsend/core";
+import type { DurationObject } from "@hogsend/core";
 import { durationToMs, evaluateEventCondition } from "@hogsend/core";
 import type { JourneyRegistry } from "@hogsend/core/registry";
 import {
@@ -69,7 +69,6 @@ interface JourneyContextConfig {
   };
   registry: JourneyRegistry;
   logger: Logger;
-  posthog?: PostHogService;
   stateId: string;
   userId: string;
   userEmail: string;
@@ -140,7 +139,6 @@ export function createJourneyContext(
     hatchetCtx,
     registry,
     logger,
-    posthog,
     stateId,
     userId,
     userEmail,
@@ -316,10 +314,6 @@ export function createJourneyContext(
       });
     },
 
-    identify(properties) {
-      posthog?.identify(userId, properties);
-    },
-
     guard: {
       async isSubscribed() {
         const prefs = await checkEmailPreferences({ db, userId });
@@ -390,15 +384,5 @@ export function createJourneyContext(
         };
       },
     },
-
-    posthog: {
-      capture({ event, properties }) {
-        posthog?.captureEvent({
-          distinctId: userId,
-          event,
-          properties,
-        });
-      },
-    },
   };
 }

package/src/lib/analytics-singleton.ts

@@ -6,6 +6,13 @@ import { createOptionalSingleton } from "./singleton.js";
  * the module-level task-execution sites that have no client reference of their
  * own (the journey durable task in `define-journey`, the bucket PostHog sync).
  *
+ * Its role is deliberately NARROW (see the `analytics?` option doc on
+ * {@link createHogsendClient}): the identity PULL (`getPersonProperties` for
+ * per-user timezone resolution) and the opt-in `bucket.syncToPostHog`
+ * person-property mirror. It is explicitly NOT the outbound-catalog firing
+ * path — the email/contact/journey/bucket lifecycle fans out durably via
+ * DESTINATIONS on the webhook spine, not through this singleton.
+ *
  * Mirrors the journey/bucket-registry + client-schedule-defaults singletons:
  * `createHogsendClient` runs in BOTH the API and worker processes, so by the
  * time any worker task executes, the container has already installed the

package/src/lib/mailer.ts

@@ -210,9 +210,10 @@ export function createTrackedMailer(
       case "email.opened":
       case "email.clicked":
         // First-party pixel/redirect is the SINGLE outbound emitter for
-        // open/click (gated on the first-touch null→set UPDATE in the tracking
-        // routes — risk 4). The provider-webhook echo is SUPPRESSED here: it only
-        // updates the DB status, it does NOT emit outbound (no double-source).
+        // open/click — it now fires PER-HIT (every open/click → a delivery to
+        // every destination, owner decision 1). The provider-webhook echo is
+        // SUPPRESSED here: it only updates the DB status, it does NOT emit
+        // outbound (no double-source).
         await updateEmailStatus(event.type, event.data.email_id);
         break;
       case "email.bounced":
@@ -229,6 +230,9 @@ export function createTrackedMailer(
         break;
       case "email.complained":
         await updateEmailStatus(event.type, event.data.email_id);
+        // OUTBOUND `email.complained` — the provider webhook is the SINGLE
+        // source for complaints (no first-party signal exists).
+        await emitProviderEmailEvent("email.complained", event.data.email_id);
         await handleComplaint(event.data.to);
         break;
       case "email.delivery_delayed":
@@ -279,8 +283,10 @@ export function createTrackedMailer(
   }
 
   /**
-   * Emit the provider-funnel outbound event (`email.delivered` / `email.bounced`)
-   * for a Resend `email_id`. Enriches via {@link resolveEmailSendContextByResendId}
+   * Emit the provider-funnel outbound event (`email.delivered` /
+   * `email.bounced` / `email.complained`) for a Resend `email_id`. These three
+   * have no first-party signal — the provider webhook is their single source.
+   * Enriches via {@link resolveEmailSendContextByResendId}
    * (the only handle a provider webhook holds is the Resend id). Fire-and-forget:
    * a missing context (webhook racing the send-row commit) or a transient outbound
    * error is logged and swallowed — never failing the webhook handler. No
@@ -288,7 +294,7 @@ export function createTrackedMailer(
    * shared `Webhook-Id` is the subscriber-side dedup for any provider redelivery.
    */
   function emitProviderEmailEvent(
-    event: "email.delivered" | "email.bounced",
+    event: "email.delivered" | "email.bounced" | "email.complained",
     resendId: string,
     bounce?: { bounceType?: string; bounceReason?: string },
   ): void {
@@ -321,6 +327,15 @@ export function createTrackedMailer(
             },
           });
         }
+        if (event === "email.complained") {
+          return emitOutbound({
+            db: database,
+            hatchet,
+            logger: log,
+            event: "email.complained",
+            payload: base,
+          });
+        }
         return emitOutbound({
           db: database,
           hatchet,

package/src/lib/outbound.ts

@@ -33,6 +33,9 @@ interface EmailEventPayload {
   userId: string | null;
   to: string;
   at: string;
+  // Optional enrichment (additive — older subscribers ignore absent keys).
+  category?: string;
+  subject?: string;
 }
 
 interface BucketEventPayload {
@@ -82,6 +85,10 @@ export interface OutboundPayloads {
     bounceType?: string;
     bounceReason?: string;
   };
+  "email.complained": EmailEventPayload & {
+    complaintType?: string;
+    reason?: string;
+  };
   "journey.completed": {
     journeyId: string;
     journeyName: string;

package/src/lib/seed-posthog-destination.ts

@@ -0,0 +1,93 @@
+import { type Database, webhookEndpoints } from "@hogsend/db";
+import { and, eq, isNull, sql } from "drizzle-orm";
+import type { Logger } from "./logger.js";
+
+/**
+ * Transaction-scoped advisory-lock key serializing the single-tenant PostHog
+ * seed across concurrent API + worker boots. An arbitrary fixed constant within
+ * int4 range (the single-arg `pg_advisory_xact_lock` overload casts to bigint).
+ */
+const SEED_ADVISORY_LOCK_KEY = 1426198835;
+
+/**
+ * The email funnel a seeded PostHog destination subscribes to — the full
+ * lifecycle that reaches PostHog on NO path before this destination existed.
+ */
+const POSTHOG_FUNNEL_EVENTS = [
+  "email.sent",
+  "email.delivered",
+  "email.opened",
+  "email.clicked",
+  "email.bounced",
+  "email.complained",
+] as const;
+
+/**
+ * Idempotently seed ONE `kind="posthog"` webhook endpoint subscribed to the
+ * email funnel, so the full email lifecycle fans out to PostHog DURABLY on the
+ * delivery spine.
+ *
+ * Guarded against duplicates: it inserts only when no single-tenant
+ * (`organization_id IS NULL`) `kind="posthog"` endpoint already exists. Safe to
+ * call from BOTH the API and worker boots (both build the client) — the second
+ * caller finds the row and no-ops. Fire-and-forget at the call site: a transient
+ * seed failure must never block boot.
+ */
+export async function seedPostHogDestination(opts: {
+  db: Database;
+  logger: Logger;
+  apiKey: string;
+  host?: string;
+}): Promise<{ seeded: boolean }> {
+  const { db, logger, apiKey, host } = opts;
+
+  // Serialize the check-then-insert across concurrent API + worker boots (both
+  // build the client) with a transaction-scoped advisory lock, so the race can
+  // never double-seed. A per-endpoint unique constraint is intentionally avoided
+  // — operators may legitimately create multiple PostHog endpoints by hand.
+  return db.transaction(async (tx) => {
+    await tx.execute(
+      sql`SELECT pg_advisory_xact_lock(${SEED_ADVISORY_LOCK_KEY})`,
+    );
+
+    const existing = await tx
+      .select({ id: webhookEndpoints.id })
+      .from(webhookEndpoints)
+      .where(
+        and(
+          isNull(webhookEndpoints.organizationId),
+          eq(webhookEndpoints.kind, "posthog"),
+        ),
+      )
+      .limit(1);
+
+    if (existing.length > 0) {
+      return { seeded: false };
+    }
+
+    await tx.insert(webhookEndpoints).values({
+      url: "posthog://capture",
+      description:
+        "Auto-seeded PostHog destination (ENABLE_POSTHOG_DESTINATION)",
+      kind: "posthog",
+      config: {
+        apiKey,
+        ...(host ? { host } : {}),
+        // Preserve continuity with the legacy fire-and-forget PostHog path,
+        // which captured clicks as "email.link_clicked"; the posthog transform
+        // remaps the canonical "email.clicked" back so existing PostHog funnels
+        // keep working after the cutover.
+        eventNames: { "email.clicked": "email.link_clicked" },
+      },
+      eventTypes: [...POSTHOG_FUNNEL_EVENTS],
+      secret: null,
+      secretPrefix: null,
+      disabled: false,
+    });
+
+    logger.info("Seeded PostHog destination on the outbound spine", {
+      events: POSTHOG_FUNNEL_EVENTS.length,
+    });
+    return { seeded: true };
+  });
+}

package/src/lib/tracking-events.ts

@@ -1,5 +1,4 @@
 import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
-import type { PostHogService } from "@hogsend/core";
 import type { JourneyRegistry } from "@hogsend/core/registry";
 import { type Database, emailSends, journeyStates } from "@hogsend/db";
 import { eq } from "drizzle-orm";
@@ -98,7 +97,6 @@ export interface PushTrackingEventOpts {
   hatchet: HatchetClient;
   registry: JourneyRegistry;
   logger: Logger;
-  posthog?: PostHogService;
   event: string;
   emailSendId: string;
   properties?: Record<string, unknown>;
@@ -111,10 +109,20 @@ export interface PushTrackingEventOpts {
   resolvedContext?: EmailSendContext | null;
 }
 
+/**
+ * Re-push a first-party tracking event (open/click) back onto the INTERNAL bus
+ * (`ingestEvent`) for journey routing + `userEvents` persistence.
+ *
+ * NOTE (Phase 2): this NO LONGER fires a fire-and-forget PostHog `captureEvent`.
+ * PostHog now receives opens/clicks PER-HIT via the durable outbound spine — a
+ * `kind="posthog"` destination subscribed to `email.opened`/`email.clicked` (the
+ * tracking routes call `emitOutbound` alongside this). The legacy double-emit was
+ * removed so PostHog gets exactly one, durable copy of each hit.
+ */
 export async function pushTrackingEvent(
   opts: PushTrackingEventOpts,
 ): Promise<void> {
-  const { db, hatchet, registry, logger, posthog, event, emailSendId } = opts;
+  const { db, hatchet, registry, logger, event, emailSendId } = opts;
 
   const ctx =
     opts.resolvedContext !== undefined
@@ -128,12 +136,6 @@ export async function pushTrackingEvent(
     ...opts.properties,
   };
 
-  posthog?.captureEvent({
-    distinctId: ctx.userId,
-    event,
-    properties,
-  });
-
   await ingestEvent({
     db,
     registry,

package/src/lib/webhook-signing.ts

@@ -25,7 +25,7 @@ import { Webhook } from "svix";
  */
 
 /**
- * The 12-event catalog — the SINGLE source of truth (schema, routes, client,
+ * The 13-event catalog — the SINGLE source of truth (schema, routes, client,
  * CLI all derive from this). The `webhook.test` sentinel is intentionally NOT a
  * member (it is delivered out-of-band regardless of an endpoint's `eventTypes`).
  */
@@ -39,6 +39,7 @@ export const WEBHOOK_EVENT_TYPES = [
   "email.opened",
   "email.clicked",
   "email.bounced",
+  "email.complained",
   "journey.completed",
   "bucket.entered",
   "bucket.left",

package/src/routes/admin/webhooks.ts

@@ -3,6 +3,7 @@ import { webhookDeliveries, webhookEndpoints } from "@hogsend/db";
 import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
 import { count, desc, eq } from "drizzle-orm";
 import type { AppEnv } from "../../app.js";
+import { PRESET_DESTINATIONS } from "../../destinations/presets/index.js";
 import { errorSchema } from "../../lib/schemas.js";
 import {
   generateWebhookSecret,
@@ -24,17 +25,34 @@ import { deliverWebhookTask } from "../../workflows/deliver-webhook.js";
 
 // The catalog enum for request validation — derived from the SINGLE source of
 // truth in `webhook-signing.ts` (Section 1.3). `z.enum` needs a non-empty tuple,
-// which `WEBHOOK_EVENT_TYPES` (12 strings, `as const`) satisfies.
+// which `WEBHOOK_EVENT_TYPES` (13 strings, `as const`) satisfies.
 const eventTypeEnum = z.enum(
   WEBHOOK_EVENT_TYPES as unknown as [WebhookEventType, ...WebhookEventType[]],
 );
 
+// The destination `kind` enum. "webhook" (default) is the signed POST; any
+// other value selects a delivery-time transform adapter keyed by this column.
+// This MUST cover every shipped preset (the skills + env.example tell operators
+// to create segment/slack endpoints via this admin API / the `hs.webhooks` SDK),
+// so it is derived from `PRESET_DESTINATIONS` — the single source of truth for
+// the shipped `kind`s — rather than a hand-maintained literal list. A `kind`
+// whose transform is not REGISTERED at delivery time still fails its delivery as
+// a config error (DLQ); the registry, not the env, decides resolvability — so we
+// accept any shipped preset id here regardless of `ENABLED_DESTINATION_PRESETS`.
+const kindEnum = z.enum(
+  Object.keys(PRESET_DESTINATIONS) as unknown as [string, ...string[]],
+);
+
 const webhookEndpointSchema = z.object({
   id: z.string(),
   url: z.string(),
   description: z.string().nullable(),
   eventTypes: z.array(z.string()),
-  secretPrefix: z.string(),
+  // Keyed destinations have no signing secret (null secretPrefix).
+  secretPrefix: z.string().nullable(),
+  kind: z.string(),
+  // REDACTED config view — credentials (e.g. config.apiKey) are masked.
+  config: z.record(z.string(), z.unknown()).nullable(),
   status: z.enum(["enabled", "disabled"]),
   organizationId: z.string().nullable(),
   lastDeliveryAt: z.string().nullable(),
@@ -85,6 +103,11 @@ const createEndpointRoute = createRoute({
             eventTypes: z.array(eventTypeEnum).min(1),
             description: z.string().max(500).optional(),
             disabled: z.boolean().optional(),
+            // Destination selector. Defaults to "webhook" (signed POST).
+            kind: kindEnum.optional(),
+            // Per-destination config for keyed adapters (e.g. PostHog's
+            // `{ apiKey, host }`). Ignored for kind="webhook".
+            config: z.record(z.string(), z.unknown()).optional(),
           }),
         },
       },
@@ -94,7 +117,11 @@ const createEndpointRoute = createRoute({
     201: {
       content: {
         "application/json": {
-          schema: webhookEndpointSchema.extend({ secret: z.string() }),
+          // `secret` is present ONLY for kind="webhook" (the one-time signing
+          // secret). Keyed destinations carry no secret.
+          schema: webhookEndpointSchema.extend({
+            secret: z.string().optional(),
+          }),
         },
       },
       description: "Endpoint created — signing secret shown only once",
@@ -139,6 +166,8 @@ const updateEndpointRoute = createRoute({
             eventTypes: z.array(eventTypeEnum).min(1).optional(),
             description: z.string().max(500).nullable().optional(),
             disabled: z.boolean().optional(),
+            kind: kindEnum.optional(),
+            config: z.record(z.string(), z.unknown()).nullable().optional(),
           }),
         },
       },
@@ -237,10 +266,30 @@ const testRoute = createRoute({
   },
 });
 
+/** Config keys whose values are credentials and must be masked in responses. */
+const REDACTED_CONFIG_KEYS = new Set(["apiKey", "apikey", "api_key"]);
+
+/**
+ * Mask credential values in a keyed destination's `config` for API responses —
+ * `config.apiKey` becomes `"***"` so a list/get never leaks the secret. Returns
+ * null when there is no config (kind="webhook").
+ */
+function redactConfig(
+  config: Record<string, unknown> | null,
+): Record<string, unknown> | null {
+  if (!config) return null;
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(config)) {
+    out[key] = REDACTED_CONFIG_KEYS.has(key) ? "***" : value;
+  }
+  return out;
+}
+
 /**
  * Serialize an endpoint row for an API response. NEVER includes `secret` — the
  * full `whsec_…` is surfaced only on create + rotate-secret via the dedicated
- * response shapes. `status` is derived from the `disabled` boolean.
+ * response shapes. `config` is REDACTED (credentials masked). `status` is
+ * derived from the `disabled` boolean.
  */
 function serializeEndpoint(row: typeof webhookEndpoints.$inferSelect) {
   return {
@@ -249,6 +298,8 @@ function serializeEndpoint(row: typeof webhookEndpoints.$inferSelect) {
     description: row.description,
     eventTypes: row.eventTypes as string[],
     secretPrefix: row.secretPrefix,
+    kind: row.kind,
+    config: redactConfig(row.config),
     status: (row.disabled ? "disabled" : "enabled") as "enabled" | "disabled",
     organizationId: row.organizationId,
     lastDeliveryAt: row.lastDeliveryAt?.toISOString() ?? null,
@@ -292,7 +343,13 @@ export const webhooksRouter = new OpenAPIHono<AppEnv>()
     const { db } = c.get("container");
     const body = c.req.valid("json");
 
-    const { secret, secretPrefix } = generateWebhookSecret();
+    const kind = body.kind ?? "webhook";
+    // Only the signed "webhook" kind gets a signing secret; keyed destinations
+    // authenticate via `config` (their secret/secretPrefix stay null).
+    const credentials =
+      kind === "webhook"
+        ? generateWebhookSecret()
+        : { secret: null, secretPrefix: null };
 
     const [created] = await db
       .insert(webhookEndpoints)
@@ -301,15 +358,24 @@ export const webhooksRouter = new OpenAPIHono<AppEnv>()
         eventTypes: body.eventTypes,
         description: body.description ?? null,
         disabled: body.disabled ?? false,
-        secret,
-        secretPrefix,
+        kind,
+        config: body.config ?? null,
+        secret: credentials.secret,
+        secretPrefix: credentials.secretPrefix,
       })
       .returning();
 
     if (!created) throw new Error("Failed to create webhook endpoint");
 
-    // The ONLY list/get-shaped response that also carries the full secret.
-    return c.json({ ...serializeEndpoint(created), secret }, 201);
+    // The ONLY list/get-shaped response that also carries the full secret — and
+    // ONLY for kind="webhook" (keyed destinations have no secret to surface).
+    if (kind === "webhook" && credentials.secret) {
+      return c.json(
+        { ...serializeEndpoint(created), secret: credentials.secret },
+        201,
+      );
+    }
+    return c.json(serializeEndpoint(created), 201);
   })
   .openapi(getEndpointRoute, async (c) => {
     const { db } = c.get("container");
@@ -349,6 +415,19 @@ export const webhooksRouter = new OpenAPIHono<AppEnv>()
     if (body.eventTypes !== undefined) patch.eventTypes = body.eventTypes;
     if (body.description !== undefined) patch.description = body.description;
     if (body.disabled !== undefined) patch.disabled = body.disabled;
+    if (body.kind !== undefined) patch.kind = body.kind;
+    if (body.config !== undefined) patch.config = body.config;
+
+    // Foot-gun guard: an endpoint that ends up as a signed "webhook" with no
+    // secret would dead-letter every delivery (the webhook transform signs with
+    // the live secret). Mint one when switching to (or back to) kind="webhook"
+    // without an existing secret. Keyed kinds keep their null secret — harmless.
+    const effectiveKind = body.kind ?? existing.kind;
+    if (effectiveKind === "webhook" && !existing.secret) {
+      const { secret, secretPrefix } = generateWebhookSecret();
+      patch.secret = secret;
+      patch.secretPrefix = secretPrefix;
+    }
 
     const [updated] = await db
       .update(webhookEndpoints)
@@ -418,6 +497,14 @@ export const webhooksRouter = new OpenAPIHono<AppEnv>()
     // endpoint's `eventTypes`. Build a synthetic delivery row directly — it does
     // NOT go through `emitOutbound` (which filters by subscription) — then enqueue
     // the same durable delivery task the live emit path uses.
+    //
+    // The synthetic envelope routes THROUGH the per-kind delivery adapter (the
+    // delivery task resolves it by `endpoint.kind`), so the `data` must carry the
+    // fields every adapter needs to build a VALID request. For `kind="webhook"`
+    // the adapter only signs the frozen bytes, so the extra fields are harmless;
+    // for `kind="posthog"` the capture adapter coalesces `distinct_id` from
+    // `userId`/`to`/`userEmail`, so a synthetic recipient (`to`) is required or
+    // the test would POST a malformed capture with no distinct_id.
     const webhookId = `msg_${randomUUID()}`;
     const timestamp = new Date();
     const envelope = {
@@ -428,6 +515,10 @@ export const webhooksRouter = new OpenAPIHono<AppEnv>()
         message: "Hogsend test event",
         endpointId: endpoint.id,
         sentAt: timestamp.toISOString(),
+        // Adapter-friendly synthetic identity so a keyed destination (e.g.
+        // posthog) builds a valid request from the test envelope.
+        userId: `test_${endpoint.id}`,
+        to: "test@hogsend.com",
       },
     };