Add OAS spec and Scalar docs to standalone webhook server

- webhook-app.ts: add /health, /openapi.json, and /docs routes
- open-docs.sh: add `webhook` option (port 4030)
- generate-openapi.sh: generate and check webhook.json alongside engine/service

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Committed-By-Agent: claude

Author: tonyxiao

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

@@ -1,4 +1,5 @@
 import { OpenAPIHono, createRoute, z } from '@hono/zod-openapi'
+import { apiReference } from '@scalar/hono-api-reference'
 
 export interface WebhookAppOptions {
   /** Called for each incoming webhook event. Fire-and-forget. */
@@ -66,6 +67,24 @@ export function createWebhookApp({ push_event }: WebhookAppOptions) {
       }
     },
   })
+  app.get('/health', (c) => c.text('ok'))
+
   mountWebhookRoutes(app, push_event)
+
+  app.get('/openapi.json', (c) =>
+    c.json(
+      app.getOpenAPIDocument({
+        openapi: '3.0.0',
+        info: {
+          title: 'Stripe Sync Webhook Server',
+          version: '1.0.0',
+          description: 'Standalone webhook ingress — receives Stripe webhook events.',
+        },
+      })
+    )
+  )
+
+  app.get('/docs', apiReference({ url: '/openapi.json' }))
+
   return app
 }

docs/openapi/webhook.json

@@ -0,0 +1,46 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "Stripe Sync Webhook Server",
+    "version": "1.0.0",
+    "description": "Standalone webhook ingress — receives Stripe webhook events."
+  },
+  "components": {
+    "schemas": {},
+    "parameters": {}
+  },
+  "paths": {
+    "/webhooks/{credential_id}": {
+      "post": {
+        "operationId": "pushWebhook",
+        "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.",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "example": "cred_abc123"
+            },
+            "required": true,
+            "name": "credential_id",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Event accepted",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "enum": ["ok"]
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

scripts/generate-openapi.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
-# Generate OpenAPI specs from both engine and service apps.
-# Output: docs/openapi/engine.json, docs/openapi/service.json
+# Generate OpenAPI specs from engine, service, and webhook apps.
+# Output: docs/openapi/{engine,service,webhook}.json
 set -euo pipefail
 
 cd "$(dirname "$0")/.."
@@ -36,11 +36,20 @@ node -e "
   process.stdout.write(JSON.stringify(spec, null, 2) + '\n');
 " > "$outdir/service.json"
 
-pnpm prettier --write "$outdir/engine.json" "$outdir/service.json" --log-level warn
+echo "Generating webhook OpenAPI spec..."
+node -e "
+  import { createWebhookApp } from './apps/service/dist/api/webhook-app.js';
+  const app = createWebhookApp({ push_event: () => {} });
+  const res = await app.request('/openapi.json');
+  const spec = await res.json();
+  process.stdout.write(JSON.stringify(spec, null, 2) + '\n');
+" > "$outdir/webhook.json"
+
+pnpm prettier --write "$outdir/engine.json" "$outdir/service.json" "$outdir/webhook.json" --log-level warn
 
 if $check_mode; then
   drift=false
-  for spec in engine.json service.json; do
+  for spec in engine.json service.json webhook.json; do
     if ! diff -q "$outdir/$spec" "docs/openapi/$spec" > /dev/null 2>&1; then
       echo "DRIFT: docs/openapi/$spec is out of date"
       diff --unified "$outdir/$spec" "docs/openapi/$spec" || true
@@ -57,4 +66,5 @@ else
   echo "Done:"
   echo "  docs/openapi/engine.json  ($(wc -l < docs/openapi/engine.json) lines)"
   echo "  docs/openapi/service.json ($(wc -l < docs/openapi/service.json) lines)"
+  echo "  docs/openapi/webhook.json ($(wc -l < docs/openapi/webhook.json) lines)"
 fi

scripts/open-docs.sh

@@ -1,18 +1,19 @@
 #!/usr/bin/env bash
-# Start engine or service API server and open Scalar docs in the browser.
-# Usage: ./scripts/open-docs.sh [engine|service]
+# Start engine, service, or webhook server and open Scalar docs in the browser.
+# Usage: ./scripts/open-docs.sh [engine|service|webhook]
 set -euo pipefail
 
 APP="${1:-engine}"
 RUN="$(dirname "$0")/ts-run"
 
 case "$APP" in
-  engine)  PORT="${PORT:-3000}"; ENTRY="apps/engine/src/cli/index.ts" ;;
-  service) PORT="${PORT:-4020}"; ENTRY="apps/service/src/bin/cli.ts" ;;
-  *) echo "Usage: $0 [engine|service]" >&2; exit 1 ;;
+  engine)  PORT="${PORT:-3000}"; ENTRY="apps/engine/src/cli/index.ts";  CMD_ARGS="serve --port $PORT" ;;
+  service) PORT="${PORT:-4020}"; ENTRY="apps/service/src/bin/cli.ts";   CMD_ARGS="serve --port $PORT" ;;
+  webhook) PORT="${PORT:-4030}"; ENTRY="apps/service/src/bin/cli.ts";   CMD_ARGS="webhook --port $PORT --temporal-address localhost:7233" ;;
+  *) echo "Usage: $0 [engine|service|webhook]" >&2; exit 1 ;;
 esac
 
-CMD="$RUN $ENTRY serve --port $PORT"
+CMD="$RUN $ENTRY $CMD_ARGS"
 
 cd "$(dirname "$0")/.."