feat(service): split webhook ingress into its own app and CLI subcommand

Extract the webhook route into `createWebhookApp({ push_event })` — a thin,
standalone Hono app with no CRUD machinery. The main service app mounts it via
`app.route('')` so existing behavior is unchanged.

Add `sync-service webhook` subcommand for production deployments where webhook
ingress runs on its own host/port (Temporal mode only). It creates a
TemporalBridge directly — no full SyncService needed.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Committed-By-Agent: claude

Author: tonyxiao

apps/service/src/api/app.ts

@@ -23,6 +23,7 @@ import {
   fileStateStore,
   fileLogSink,
 } from '../lib/stores-fs.js'
+import { createWebhookApp } from './webhook-app.js'
 
 // MARK: - Helpers
 
@@ -118,13 +119,6 @@ export function createApp(options?: AppOptions) {
     id: z.string().openapi({ param: { name: 'id', in: 'path' }, example: 'sync_abc123' }),
   })
 
-  const WebhookParam = z.object({
-    credential_id: z.string().openapi({
-      param: { name: 'credential_id', in: 'path' },
-      example: 'cred_abc123',
-    }),
-  })
-
   // ── Health ──────────────────────────────────────────────────────
 
   app.openapi(
@@ -800,33 +794,9 @@ export function createApp(options?: AppOptions) {
     }
   )
 
-  // MARK: - Webhook ingress
+  // MARK: - Webhook ingress (mounted from webhook-app.ts)
 
-  app.openapi(
-    createRoute({
-      operationId: 'pushWebhook',
-      method: 'post',
-      path: '/webhooks/{credential_id}',
-      tags: ['Webhooks'],
-      summary: 'Ingest a Stripe webhook event',
-      description:
-        "Receives a raw Stripe webhook event, verifies its signature using the credential's webhook secret, and enqueues it for processing by the active sync.",
-      request: { params: WebhookParam },
-      responses: {
-        200: {
-          content: { 'text/plain': { schema: z.literal('ok') } },
-          description: 'Event accepted',
-        },
-      },
-    }),
-    async (c) => {
-      const { credential_id } = c.req.valid('param')
-      const body = await c.req.text()
-      const headers = Object.fromEntries(c.req.raw.headers.entries())
-      service.push_event(credential_id, { body, headers })
-      return c.text('ok', 200)
-    }
-  )
+  app.route('', createWebhookApp({ push_event: (id, e) => service.push_event(id, e) }))
 
   // MARK: - OpenAPI spec + Swagger UI
 

apps/service/src/api/webhook-app.ts

@@ -0,0 +1,63 @@
+import { OpenAPIHono, createRoute, z } from '@hono/zod-openapi'
+
+export interface WebhookAppOptions {
+  /** Called for each incoming webhook event. Fire-and-forget. */
+  push_event: (credentialId: string, event: unknown) => void
+}
+
+/**
+ * Standalone webhook ingress app — POST /webhooks/{credential_id}.
+ *
+ * Deliberately thin: no credential management, no sync CRUD. Just receives a
+ * raw Stripe event and hands it off to `push_event`, which in Temporal mode
+ * signals the matching workflow(s) via TemporalBridge.
+ *
+ * Used in two ways:
+ *   1. Mounted inside the main service app for single-process dev.
+ *   2. As a standalone server via `sync-service webhook` for production
+ *      deployments where webhook ingress runs on its own port/host.
+ */
+export function createWebhookApp({ push_event }: WebhookAppOptions) {
+  const app = new OpenAPIHono({
+    defaultHook: (result, c) => {
+      if (!result.success) {
+        return c.json({ error: result.error.issues }, 400)
+      }
+    },
+  })
+
+  const WebhookParam = z.object({
+    credential_id: z.string().openapi({
+      param: { name: 'credential_id', in: 'path' },
+      example: 'cred_abc123',
+    }),
+  })
+
+  app.openapi(
+    createRoute({
+      operationId: 'pushWebhook',
+      method: 'post',
+      path: '/webhooks/{credential_id}',
+      tags: ['Webhooks'],
+      summary: 'Ingest a Stripe webhook event',
+      description:
+        "Receives a raw Stripe webhook event, verifies its signature using the credential's webhook secret, and enqueues it for processing by the active sync.",
+      request: { params: WebhookParam },
+      responses: {
+        200: {
+          content: { 'text/plain': { schema: z.literal('ok') } },
+          description: 'Event accepted',
+        },
+      },
+    }),
+    async (c) => {
+      const { credential_id } = c.req.valid('param')
+      const body = await c.req.text()
+      const headers = Object.fromEntries(c.req.raw.headers.entries())
+      push_event(credential_id, { body, headers })
+      return c.text('ok', 200)
+    }
+  )
+
+  return app
+}

apps/service/src/cli/main.ts

@@ -1,4 +1,5 @@
 import path from 'node:path'
+import os from 'node:os'
 import { Readable } from 'node:stream'
 import { defineCommand } from 'citty'
 import { createCliFromSpec } from '@stripe/sync-ts-cli/openapi'
@@ -125,6 +126,53 @@ const workerCmd = defineCommand({
   },
 })
 
+// Standalone webhook ingress command (Temporal mode only)
+const webhookCmd = defineCommand({
+  meta: { name: 'webhook', description: 'Start the webhook ingress server (Temporal mode)' },
+  args: {
+    port: {
+      type: 'string',
+      default: '4030',
+      description: 'HTTP server port (default: 4030)',
+    },
+    'data-dir': {
+      type: 'string',
+      description: 'Data directory — must point at the same store as the sync service',
+    },
+    'temporal-address': {
+      type: 'string',
+      required: true,
+      description: 'Temporal server address (e.g. localhost:7233)',
+    },
+    'temporal-task-queue': {
+      type: 'string',
+      default: 'sync-engine',
+      description: 'Temporal task queue name (default: sync-engine)',
+    },
+  },
+  async run({ args }) {
+    const { fileConfigStore } = await import('../lib/stores-fs.js')
+    const { TemporalBridge } = await import('../temporal/bridge.js')
+    const { createWebhookApp } = await import('../api/webhook-app.js')
+
+    const temporal = await createTemporalClient(
+      args['temporal-address'],
+      args['temporal-task-queue'] || 'sync-engine'
+    )
+    const dataDir =
+      args['data-dir'] || process.env.DATA_DIR || path.join(os.homedir(), '.stripe-sync')
+    const configs = fileConfigStore(`${dataDir}/syncs`)
+    const bridge = new TemporalBridge(temporal.client, temporal.taskQueue, configs)
+
+    const app = createWebhookApp({ push_event: (id, e) => bridge.pushEvent(id, e) })
+    const port = Number(args.port)
+    serve({ fetch: app.fetch, port }, () => {
+      console.log(`Webhook server listening on http://localhost:${port}`)
+      console.log(`  Temporal: ${args['temporal-address']} (queue: ${args['temporal-task-queue'] || 'sync-engine'})`)
+    })
+  },
+})
+
 export async function createProgram(opts?: { dataDir?: string }) {
   const app = createApp({ dataDir: opts?.dataDir })
   const res = await app.request('/openapi.json')
@@ -155,6 +203,6 @@ export async function createProgram(opts?: { dataDir?: string }) {
 
   return defineCommand({
     ...specCli,
-    subCommands: { serve: serveCmd, worker: workerCmd, ...specCli.subCommands },
+    subCommands: { serve: serveCmd, worker: workerCmd, webhook: webhookCmd, ...specCli.subCommands },
   })
 }

apps/service/src/index.ts

@@ -41,6 +41,10 @@ export type { TemporalOptions } from './temporal/bridge.js'
 export { createApp } from './api/app.js'
 export type { AppOptions } from './api/app.js'
 
+// Standalone webhook ingress app
+export { createWebhookApp } from './api/webhook-app.js'
+export type { WebhookAppOptions } from './api/webhook-app.js'
+
 // Temporal workflow types (for consumers that need to reference them)
 export type { RunResult, SyncActivities, WorkflowStatus } from './temporal/types.js'
 export { createActivities } from './temporal/activities.js'