@hogsend/engine 0.8.0 → 0.10.0

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";
@@ -10,7 +9,7 @@ interface EmailSendContext {
   userId: string;
   userEmail: string;
   templateKey: string | null;
-  resendId: string | null;
+  messageId: string | null;
   to: string;
 }
 
@@ -22,7 +21,7 @@ export async function resolveEmailSendContext(
     .select({
       toEmail: emailSends.toEmail,
       templateKey: emailSends.templateKey,
-      resendId: emailSends.resendId,
+      messageId: emailSends.messageId,
       userId: journeyStates.userId,
       userEmail: journeyStates.userEmail,
     })
@@ -38,12 +37,12 @@ export async function resolveEmailSendContext(
     userId: row.userId ?? row.toEmail,
     userEmail: row.userEmail ?? row.toEmail,
     templateKey: row.templateKey,
-    resendId: row.resendId,
+    messageId: row.messageId,
     to: row.toEmail,
   };
 }
 
-export interface ResendEmailSendContext {
+export interface EmailSendContextByMessageId {
   emailSendId: string;
   userId: string;
   userEmail: string;
@@ -51,21 +50,28 @@ export interface ResendEmailSendContext {
   to: string;
 }
 
+/**
+ * @deprecated Renamed to {@link EmailSendContextByMessageId} as part of the
+ * provider-neutral `resendId` → `messageId` rename. Kept as an alias for one
+ * minor; removed the following minor.
+ */
+export type ResendEmailSendContext = EmailSendContextByMessageId;
+
 /**
  * Mirror of {@link resolveEmailSendContext} that resolves by the provider's
- * `resendId` instead of the internal `email_sends.id`. Used by the
+ * `messageId` instead of the internal `email_sends.id`. Used by the
  * provider-webhook enrichment path (`email.delivered`/`email.bounced`) where the
- * only handle we hold is the Resend `email_id`.
+ * only handle we hold is the provider message id.
  *
  * Returns the internal `emailSendId` plus the same denormalized identity
  * (`userId`/`userEmail` fall back to the recipient address, exactly like the
  * id-keyed resolver) and `to` recipient. Returns null when no send row carries
- * that `resendId` yet (e.g. a webhook arriving before the send row is committed).
+ * that `messageId` yet (e.g. a webhook arriving before the send row is committed).
  */
-export async function resolveEmailSendContextByResendId(
+export async function resolveEmailSendContextByMessageId(
   db: Database,
-  resendId: string,
-): Promise<ResendEmailSendContext | null> {
+  messageId: string,
+): Promise<EmailSendContextByMessageId | null> {
   const rows = await db
     .select({
       emailSendId: emailSends.id,
@@ -78,7 +84,7 @@ export async function resolveEmailSendContextByResendId(
     })
     .from(emailSends)
     .leftJoin(journeyStates, eq(emailSends.journeyStateId, journeyStates.id))
-    .where(eq(emailSends.resendId, resendId))
+    .where(eq(emailSends.messageId, messageId))
     .limit(1);
 
   const row = rows[0];
@@ -93,12 +99,19 @@ export async function resolveEmailSendContextByResendId(
   };
 }
 
+/**
+ * @deprecated Renamed to {@link resolveEmailSendContextByMessageId} as part of
+ * the provider-neutral `resendId` → `messageId` rename. Kept as an alias for one
+ * minor; removed the following minor.
+ */
+export const resolveEmailSendContextByResendId =
+  resolveEmailSendContextByMessageId;
+
 export interface PushTrackingEventOpts {
   db: Database;
   hatchet: HatchetClient;
   registry: JourneyRegistry;
   logger: Logger;
-  posthog?: PostHogService;
   event: string;
   emailSendId: string;
   properties?: Record<string, unknown>;
@@ -111,10 +124,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 +151,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/emails.ts

@@ -26,6 +26,8 @@ const emailSchema = z.object({
   id: z.string(),
   journeyStateId: z.string().nullable(),
   templateKey: z.string().nullable(),
+  messageId: z.string().nullable(),
+  /** @deprecated Mirrors `messageId`; kept for one minor, removed thereafter. */
   resendId: z.string().nullable(),
   fromEmail: z.string(),
   toEmail: z.string(),
@@ -88,7 +90,9 @@ function serializeEmail(
     id: row.id,
     journeyStateId: row.journeyStateId,
     templateKey: row.templateKey,
-    resendId: row.resendId,
+    messageId: row.messageId,
+    // @deprecated Mirror of `messageId` for one minor (back-compat).
+    resendId: row.messageId,
     fromEmail: row.fromEmail,
     toEmail: row.toEmail,
     subject: row.subject,

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",
       },
     };
 

package/src/routes/tracking/click.ts

@@ -52,10 +52,11 @@ export const clickRouter = new OpenAPIHono<AppEnv>().openapi(
       null;
     const userAgent = c.req.header("user-agent") ?? null;
 
-    // The `clickedAt` first-touch UPDATE is split OUT of the Promise.all so it can
-    // `.returning({ id })` — the `WHERE clickedAt IS NULL` makes a row come back
-    // ONLY on the first click, which gates the outbound `email.clicked` emit.
-    const [, , clicked] = await Promise.all([
+    // First-touch state UPDATE: the `WHERE clickedAt IS NULL` sets `clickedAt`
+    // exactly once (the first click), which is the row-level state we keep. The
+    // outbound emit is NO LONGER gated on this — every destination must receive
+    // EVERY click (owner decision 1), so the emit below fires per-hit.
+    await Promise.all([
       db.insert(linkClicks).values({
         trackedLinkId: link.id,
         ipAddress: ip,
@@ -79,25 +80,17 @@ export const clickRouter = new OpenAPIHono<AppEnv>().openapi(
             eq(emailSends.id, link.emailSendId),
             isNull(emailSends.clickedAt),
           ),
-        )
-        .returning({ id: emailSends.id }),
+        ),
     ]);
 
-    const {
-      hatchet,
-      registry,
-      logger,
-      analytics: posthog,
-    } = c.get("container");
+    const { hatchet, registry, logger } = c.get("container");
 
     // Resolve the send context ONCE (off the response path) and feed both the
-    // re-ingest (every click) and the first-touch outbound emit (first click
-    // only) — avoiding a duplicate `resolveEmailSendContext` read on the click
-    // hot path. `dedupeKey` = `email.clicked:<emailSendId>` is defence-in-depth
-    // alongside the first-touch gate (`clicked.length > 0`); first-party is the
-    // SINGLE emitter for `email.clicked` (the provider-webhook echo is suppressed).
+    // re-ingest and the PER-HIT outbound emit — avoiding a duplicate
+    // `resolveEmailSendContext` read on the click hot path. NO `dedupeKey`: a
+    // NULL dedupe key is distinct in Postgres, so every click creates a fresh
+    // delivery to every subscribed destination (per-hit, not first-touch).
     const emailSendId = link.emailSendId;
-    const isFirstClick = clicked.length > 0;
     void resolveEmailSendContext(db, emailSendId)
       .then(async (ctx) => {
         await pushTrackingEvent({
@@ -105,7 +98,6 @@ export const clickRouter = new OpenAPIHono<AppEnv>().openapi(
           hatchet,
           registry,
           logger,
-          posthog,
           event: EMAIL_LINK_CLICKED,
           emailSendId,
           properties: { linkUrl: link.originalUrl, linkId: link.id },
@@ -117,19 +109,22 @@ export const clickRouter = new OpenAPIHono<AppEnv>().openapi(
           });
         });
 
-        if (isFirstClick) {
+        // Only emit when the send-context resolved. A missing emailSends row
+        // (orphaned tracked link / deleted send) has no userId or recipient to
+        // attribute, and a keyed destination (PostHog) would otherwise receive
+        // an empty distinct_id. A normal click always resolves a non-null userId.
+        if (ctx) {
           await emitOutbound({
             db,
             hatchet,
             logger,
             event: "email.clicked",
-            dedupeKey: `email.clicked:${emailSendId}`,
             payload: {
               emailSendId,
-              resendId: ctx?.resendId ?? null,
-              templateKey: ctx?.templateKey ?? null,
-              userId: ctx?.userId ?? null,
-              to: ctx?.to ?? ctx?.userEmail ?? "",
+              messageId: ctx.messageId ?? null,
+              templateKey: ctx.templateKey ?? null,
+              userId: ctx.userId ?? null,
+              to: ctx.to ?? ctx.userEmail ?? "",
               at: new Date().toISOString(),
               linkUrl: link.originalUrl,
               linkId: link.id,

package/src/routes/tracking/open.ts

@@ -33,34 +33,25 @@ export const openRouter = new OpenAPIHono<AppEnv>().openapi(
   openRoute,
   async (c) => {
     const { id } = c.req.valid("param");
-    const {
-      db,
-      hatchet,
-      registry,
-      logger,
-      analytics: posthog,
-    } = c.get("container");
+    const { db, hatchet, registry, logger } = c.get("container");
 
-    // First-touch gate: the `WHERE openedAt IS NULL` makes this UPDATE return a
-    // row ONLY on the FIRST open. `.returning({ id })` lets the outbound emit fire
-    // exactly once — first-party is the SINGLE emitter for `email.opened` (the
-    // provider-webhook echo in the mailer is suppressed — risk 4).
-    const opened = await db
+    // First-touch state UPDATE: the `WHERE openedAt IS NULL` sets `openedAt`
+    // exactly once (the first open), which is the row-level state we keep. The
+    // outbound emit is NO LONGER gated on this — every destination must receive
+    // EVERY open (owner decision 1), so the emit below fires per-hit.
+    await db
       .update(emailSends)
       .set({
         openedAt: new Date(),
         updatedAt: new Date(),
       })
-      .where(and(eq(emailSends.id, id), isNull(emailSends.openedAt)))
-      .returning({ id: emailSends.id });
+      .where(and(eq(emailSends.id, id), isNull(emailSends.openedAt)));
 
     // Resolve the send context ONCE (off the response path) and feed both the
-    // re-ingest (every open) and the first-touch outbound emit (first open
-    // only) — avoiding a duplicate `resolveEmailSendContext` read on the pixel
-    // hot path. `dedupeKey` = `email.opened:<id>` is defence-in-depth alongside
-    // the first-touch gate (`opened.length > 0`); first-party is the SINGLE
-    // emitter for `email.opened` (the provider-webhook echo is suppressed).
-    const isFirstOpen = opened.length > 0;
+    // re-ingest and the PER-HIT outbound emit — avoiding a duplicate
+    // `resolveEmailSendContext` read on the pixel hot path. NO `dedupeKey`: a
+    // NULL dedupe key is distinct in Postgres, so every open creates a fresh
+    // delivery to every subscribed destination (per-hit, not first-touch).
     void resolveEmailSendContext(db, id)
       .then(async (ctx) => {
         await pushTrackingEvent({
@@ -68,7 +59,6 @@ export const openRouter = new OpenAPIHono<AppEnv>().openapi(
           hatchet,
           registry,
           logger,
-          posthog,
           event: EMAIL_OPENED,
           emailSendId: id,
           resolvedContext: ctx,
@@ -79,19 +69,22 @@ export const openRouter = new OpenAPIHono<AppEnv>().openapi(
           });
         });
 
-        if (isFirstOpen) {
+        // Only emit when the send-context resolved. A missing emailSends row
+        // (orphaned tracked pixel / deleted send) has no userId or recipient to
+        // attribute, and a keyed destination (PostHog) would otherwise receive
+        // an empty distinct_id. A normal open always resolves a non-null userId.
+        if (ctx) {
           await emitOutbound({
             db,
             hatchet,
             logger,
             event: "email.opened",
-            dedupeKey: `email.opened:${id}`,
             payload: {
               emailSendId: id,
-              resendId: ctx?.resendId ?? null,
-              templateKey: ctx?.templateKey ?? null,
-              userId: ctx?.userId ?? null,
-              to: ctx?.to ?? ctx?.userEmail ?? "",
+              messageId: ctx.messageId ?? null,
+              templateKey: ctx.templateKey ?? null,
+              userId: ctx.userId ?? null,
+              to: ctx.to ?? ctx.userEmail ?? "",
               at: new Date().toISOString(),
             },
           });

package/src/routes/webhooks/email-provider.ts

@@ -0,0 +1,124 @@
+import { WebhookHandshakeSignal } from "@hogsend/core";
+import { createRoute, type OpenAPIHono, z } from "@hono/zod-openapi";
+import type { Context } from "hono";
+import type { AppEnv } from "../../app.js";
+import { headersToRecord } from "../../lib/headers.js";
+
+/**
+ * Shared email-provider webhook dispatch used by BOTH the id-dispatched
+ * `POST /v1/webhooks/email/:providerId` route and the thin
+ * `POST /v1/webhooks/resend` alias. Resolves the provider from the container's
+ * {@link EmailProviderRegistry} (404 on unknown id), reads the raw body as the
+ * EXACT received bytes (signature schemes verify over these), verifies +
+ * dispatches the normalized {@link EmailEvent}, 200s a
+ * {@link WebhookHandshakeSignal}, and 401s a verification error.
+ */
+export async function dispatchProviderWebhook(
+  c: Context<AppEnv>,
+  providerId: string,
+) {
+  const { emailProviders, emailService, logger } = c.get("container");
+
+  const provider = emailProviders.get(providerId);
+  if (!provider) {
+    return c.json({ error: "Unknown email provider" }, 404);
+  }
+
+  // Read the body ONCE as the EXACT received bytes — signature schemes verify
+  // over these bytes, so we must not re-stringify.
+  const payload = await c.req.text();
+  const headers = headersToRecord(c.req.raw.headers);
+
+  try {
+    const event = await provider.verifyWebhook({ payload, headers });
+    const result = await emailService.handleWebhook(event, providerId);
+
+    logger.info("Email provider webhook processed", {
+      providerId,
+      type: event.type,
+      handled: result.handled,
+    });
+
+    return c.json({ ok: true }, 200);
+  } catch (err) {
+    if (err instanceof WebhookHandshakeSignal) {
+      // A non-delivery-status handshake (SNS confirm, Postmark subscription
+      // change) the provider already handled — ack with 200.
+      logger.info("Email webhook handshake", {
+        providerId,
+        action: err.action,
+      });
+      return c.json({ ok: true }, 200);
+    }
+    logger.warn("Email provider webhook failed", {
+      providerId,
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return c.json({ error: "Webhook verification failed" }, 401);
+  }
+}
+
+/**
+ * Id-dispatched email-provider webhook receiver:
+ * `POST /v1/webhooks/email/:providerId`.
+ *
+ * Resolves the provider from the container's {@link EmailProviderRegistry} (so
+ * an unknown id is a clean 404), verifies the webhook via that provider (which
+ * owns its OWN secrets), and dispatches the normalized {@link EmailEvent} into
+ * `emailService.handleWebhook`. Registered BEFORE the `:sourceId` catch-all so
+ * Hono matches the static `email/` prefix first.
+ *
+ * The provider's `verifyWebhook` is the ONLY place body-shape knowledge lives —
+ * the route never sniffs the payload. It returns a normalized event, OR throws
+ * {@link WebhookHandshakeSignal} for non-status handshakes (route 200s), OR
+ * throws a verification error (route 401s).
+ */
+const emailProviderWebhookRoute = createRoute({
+  method: "post",
+  path: "/v1/webhooks/email/{providerId}",
+  tags: ["Webhooks"],
+  summary: "Email provider webhook receiver",
+  request: {
+    params: z.object({ providerId: z.string() }),
+    body: {
+      content: {
+        "application/json": {
+          schema: z.record(z.string(), z.unknown()),
+        },
+      },
+    },
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({ ok: z.boolean() }),
+        },
+      },
+      description: "Webhook processed",
+    },
+    401: {
+      content: {
+        "application/json": {
+          schema: z.object({ error: z.string() }),
+        },
+      },
+      description: "Missing or invalid webhook signature",
+    },
+    404: {
+      content: {
+        "application/json": {
+          schema: z.object({ error: z.string() }),
+        },
+      },
+      description: "Unknown email provider",
+    },
+  },
+});
+
+export function registerEmailProviderRoutes(app: OpenAPIHono<AppEnv>) {
+  app.openapi(emailProviderWebhookRoute, (c) => {
+    const { providerId } = c.req.valid("param");
+    return dispatchProviderWebhook(c, providerId);
+  });
+}