@shipfox/api-integration-webhook 5.0.0 → 6.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-integration-webhook",
   "license": "MIT",
-  "version": "5.0.0",
+  "version": "6.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -22,19 +22,20 @@
     }
   },
   "dependencies": {
-    "@fastify/formbody": "^8.0.2",
     "fastify-plugin": "^5.1.0",
     "zod": "^4.4.3",
-    "@shipfox/api-auth-context": "5.0.0",
-    "@shipfox/api-integration-core-dto": "5.0.0",
-    "@shipfox/api-integration-webhook-dto": "5.0.0",
+    "@shipfox/api-auth-context": "6.0.0",
+    "@shipfox/api-integration-core-dto": "6.0.0",
+    "@shipfox/api-integration-webhook-dto": "6.0.0",
     "@shipfox/config": "1.2.2",
-    "@shipfox/node-fastify": "0.2.3"
+    "@shipfox/node-fastify": "0.2.4",
+    "@shipfox/node-opentelemetry": "0.5.2"
   },
   "devDependencies": {
     "fastify": "^5.3.3",
     "fastify-type-provider-zod": "^6.0.0",
     "@shipfox/biome": "1.8.2",
+    "@shipfox/depcruise": "1.0.2",
     "@shipfox/swc": "1.2.6",
     "@shipfox/ts-config": "1.3.8",
     "@shipfox/typescript": "1.1.7",
@@ -44,6 +45,7 @@
     "build": "shipfox-swc",
     "check": "shipfox-biome-check",
     "check:fix": "shipfox-biome-check --write",
+    "depcruise": "shipfox-depcruise",
     "test": "shipfox-vitest-run",
     "test:watch": "shipfox-vitest-watch",
     "type": "shipfox-tsc-check",

package/src/constants.ts

@@ -1,5 +1,11 @@
 export const WEBHOOK_INBOUND_BODY_LIMIT = 1 * 1024 * 1024;
 
+export const WEBHOOK_ACCEPTED_CONTENT_TYPES = [
+  'application/json',
+  'application/x-www-form-urlencoded',
+  'text/plain',
+] as const;
+
 export const WEBHOOK_FORWARDED_HEADERS = [
   'content-type',
   'user-agent',

package/src/core/webhook-processor.test.ts

@@ -0,0 +1,87 @@
+import {randomUUID} from 'node:crypto';
+import {
+  createStoredWebhookRequest,
+  type IntegrationConnection,
+} from '@shipfox/api-integration-core-dto';
+import {createGenericWebhookProcessor} from './webhook-processor.js';
+
+function fakeConnection(overrides: Partial<IntegrationConnection> = {}): IntegrationConnection {
+  const now = new Date();
+  return {
+    id: randomUUID(),
+    workspaceId: randomUUID(),
+    provider: 'webhook',
+    externalAccountId: 'stripe-prod',
+    slug: 'stripe_prod',
+    displayName: 'Stripe Production',
+    lifecycleStatus: 'active',
+    createdAt: now,
+    updatedAt: now,
+    ...overrides,
+  };
+}
+
+function genericWebhookRequest(connectionId: string) {
+  return createStoredWebhookRequest({
+    requestId: randomUUID(),
+    routeId: 'webhook.connection',
+    receivedAt: '2026-07-20T10:30:00.123Z',
+    rawQueryString: 'mode=test&tag=one&tag=two',
+    headers: {
+      'content-type': 'application/json',
+      'x-delivery-id': 'delivery-1',
+      authorization: '[redacted]',
+    },
+    body: new TextEncoder().encode('{"ok":true}'),
+    connectionId,
+  });
+}
+
+describe('GenericWebhookProcessor', () => {
+  it.each([
+    ['a missing connection', undefined],
+    ['an inactive connection', fakeConnection({lifecycleStatus: 'disabled'})],
+  ])('discards queued delivery for %s', async (_description, connection) => {
+    const publishIntegrationEventReceived = vi.fn(() => Promise.resolve({published: true}));
+    const processor = createGenericWebhookProcessor({
+      coreDb: () => ({transaction: (callback) => callback({})}),
+      getIntegrationConnectionById: vi.fn(() => Promise.resolve(connection)),
+      publishIntegrationEventReceived,
+    });
+
+    const result = await processor.process(genericWebhookRequest(randomUUID()));
+
+    expect(result).toEqual({outcome: 'discarded', reason: 'connection_unavailable'});
+    expect(publishIntegrationEventReceived).not.toHaveBeenCalled();
+  });
+
+  it('publishes the compatible generic event envelope', async () => {
+    const connection = fakeConnection();
+    const publishIntegrationEventReceived = vi.fn(() => Promise.resolve({published: true}));
+    const processor = createGenericWebhookProcessor({
+      coreDb: () => ({transaction: (callback) => callback({})}),
+      getIntegrationConnectionById: vi.fn(() => Promise.resolve(connection)),
+      publishIntegrationEventReceived,
+    });
+
+    const result = await processor.process(genericWebhookRequest(connection.id));
+
+    expect(result).toEqual({outcome: 'processed', deliveryId: 'delivery-1'});
+    expect(publishIntegrationEventReceived).toHaveBeenCalledWith({
+      tx: {},
+      event: expect.objectContaining({
+        deliveryId: 'delivery-1',
+        payload: {
+          method: 'POST',
+          headers: {
+            'content-type': 'application/json',
+            'x-delivery-id': 'delivery-1',
+            authorization: '[redacted]',
+          },
+          query: {mode: 'test', tag: ['one', 'two']},
+          body: {ok: true},
+        },
+      }),
+    });
+  });
+});

package/src/core/webhook-processor.ts

@@ -0,0 +1,128 @@
+import {Buffer} from 'node:buffer';
+import {
+  decodeWebhookBody,
+  type GetIntegrationConnectionByIdFn,
+  type IntegrationConnection,
+  type IntegrationTx,
+  type PublishIntegrationEventReceivedFn,
+  type StoredWebhookRequest,
+  type WebhookProcessingResult,
+} from '@shipfox/api-integration-core-dto';
+import {WEBHOOK_PROVIDER, WEBHOOK_RECEIVED_EVENT} from '@shipfox/api-integration-webhook-dto';
+import {logger} from '@shipfox/node-opentelemetry';
+import {redactHeaders, WEBHOOK_ACCEPTED_CONTENT_TYPES} from '#constants.js';
+
+const [JSON_CONTENT_TYPE, FORM_CONTENT_TYPE, TEXT_CONTENT_TYPE] = WEBHOOK_ACCEPTED_CONTENT_TYPES;
+
+export interface CreateGenericWebhookProcessorOptions {
+  coreDb: () => {
+    transaction<T>(callback: (tx: IntegrationTx) => Promise<T>): Promise<T>;
+  };
+  getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
+  publishIntegrationEventReceived: PublishIntegrationEventReceivedFn;
+}
+
+export interface GenericWebhookProcessor {
+  process(
+    request: StoredWebhookRequest,
+    connection?: IntegrationConnection | undefined,
+  ): Promise<WebhookProcessingResult>;
+}
+
+export function createGenericWebhookProcessor(
+  options: CreateGenericWebhookProcessorOptions,
+): GenericWebhookProcessor {
+  return {
+    process: (request, connection) => processWebhookRequest(options, request, connection),
+  };
+}
+
+async function processWebhookRequest(
+  options: CreateGenericWebhookProcessorOptions,
+  request: StoredWebhookRequest,
+  knownConnection?: IntegrationConnection | undefined,
+): Promise<WebhookProcessingResult> {
+  if (request.route_id !== 'webhook.connection') {
+    throw new Error(`Generic webhook processor cannot process ${request.route_id} requests`);
+  }
+
+  const connection =
+    knownConnection ??
+    (await options.getIntegrationConnectionById(request.path_parameters.connection_id));
+  if (
+    !connection ||
+    connection.provider !== WEBHOOK_PROVIDER ||
+    connection.lifecycleStatus !== 'active'
+  ) {
+    return {outcome: 'discarded', reason: 'connection_unavailable'};
+  }
+
+  const deliveryId = request.headers['x-delivery-id'] ?? request.request_id;
+  const body = parseWebhookBody(request);
+  if (!body.success) {
+    logger().warn({deliveryId, err: body.error}, 'generic webhook payload parsing failed');
+    return {outcome: 'discarded', reason: 'malformed_payload', deliveryId};
+  }
+
+  await options.coreDb().transaction(async (tx) => {
+    await options.publishIntegrationEventReceived({
+      tx,
+      event: {
+        provider: WEBHOOK_PROVIDER,
+        source: connection.slug,
+        event: WEBHOOK_RECEIVED_EVENT,
+        workspaceId: connection.workspaceId,
+        connectionId: connection.id,
+        connectionName: connection.displayName,
+        deliveryId,
+        receivedAt: request.received_at,
+        payload: {
+          method: request.method,
+          headers: redactHeaders(request.headers),
+          query: parseWebhookQuery(request.raw_query_string),
+          body: body.value,
+        },
+      },
+    });
+  });
+
+  return {outcome: 'processed', deliveryId};
+}
+
+function parseWebhookQuery(rawQueryString: string): Record<string, string | string[]> {
+  const query: Record<string, string | string[]> = {};
+
+  for (const [name, value] of new URLSearchParams(rawQueryString)) {
+    const existingValue = query[name];
+    if (existingValue === undefined) {
+      query[name] = value;
+    } else if (Array.isArray(existingValue)) {
+      existingValue.push(value);
+    } else {
+      query[name] = [existingValue, value];
+    }
+  }
+
+  return query;
+}
+
+function parseWebhookBody(
+  request: StoredWebhookRequest,
+): {success: true; value: unknown} | {success: false; error?: unknown} {
+  const body = Buffer.from(decodeWebhookBody(request.body));
+  const contentType = request.headers['content-type']?.split(';', 1)[0]?.trim().toLowerCase();
+
+  if (contentType === JSON_CONTENT_TYPE) {
+    try {
+      return {success: true, value: JSON.parse(body.toString('utf8'))};
+    } catch (error) {
+      return {success: false, error};
+    }
+  }
+  if (contentType === FORM_CONTENT_TYPE) {
+    return {success: true, value: Object.fromEntries(new URLSearchParams(body.toString('utf8')))};
+  }
+  if (contentType === TEXT_CONTENT_TYPE) return {success: true, value: body.toString('utf8')};
+
+  return {success: false};
+}

package/src/index.ts

@@ -9,10 +9,16 @@ import type {
 } from '@shipfox/api-integration-core-dto';
 import {WEBHOOK_PROVIDER} from '@shipfox/api-integration-webhook-dto';
 import {config} from '#config.js';
+import {createGenericWebhookProcessor} from '#core/webhook-processor.js';
 import {createWebhookConnectionRoutes} from '#presentation/routes/connections.js';
 import {createWebhookInboundRoutes} from '#presentation/routes/inbound.js';
 
 export {redactHeaders, WEBHOOK_FORWARDED_HEADERS, WEBHOOK_INBOUND_BODY_LIMIT} from '#constants.js';
+export type {
+  CreateGenericWebhookProcessorOptions,
+  GenericWebhookProcessor,
+} from '#core/webhook-processor.js';
+export {createGenericWebhookProcessor} from '#core/webhook-processor.js';
 
 export interface CreateWebhookIntegrationProviderOptions {
   coreDb: () => {
@@ -29,6 +35,7 @@ export interface CreateWebhookIntegrationProviderOptions {
 
 export function createWebhookIntegrationProvider(options: CreateWebhookIntegrationProviderOptions) {
   const baseUrl = options.baseUrl ?? config.WEBHOOK_PUBLIC_URL;
+  const webhookProcessor = createGenericWebhookProcessor(options);
   return {
     provider: WEBHOOK_PROVIDER,
     displayName: 'Webhook',
@@ -46,7 +53,9 @@ export function createWebhookIntegrationProvider(options: CreateWebhookIntegrati
         coreDb: options.coreDb,
         getIntegrationConnectionById: options.getIntegrationConnectionById,
         publishIntegrationEventReceived: options.publishIntegrationEventReceived,
+        processor: webhookProcessor,
       }),
     ],
+    webhookProcessors: [{routeIds: ['webhook.connection'] as const, processor: webhookProcessor}],
   };
 }

package/src/presentation/routes/inbound.test.ts

@@ -54,11 +54,14 @@ describe('webhook inbound route', () => {
 
   it('publishes a JSON delivery envelope', async () => {
     const connection = fakeConnection();
-    const {app, publishIntegrationEventReceived} = await createTestApp({connection});
+    const {app, publishIntegrationEventReceived, getIntegrationConnectionById} =
+      await createTestApp({
+        connection,
+      });
 
     const res = await app.inject({
       method: 'POST',
-      url: `/webhook/${connection.id}?mode=test`,
+      url: `/webhook/${connection.id}?mode=test&tag=one&tag=two`,
       headers: {
         'content-type': 'application/json',
         'x-delivery-id': 'evt-1',
@@ -80,7 +83,7 @@ describe('webhook inbound route', () => {
       deliveryId: 'evt-1',
       payload: {
         method: 'POST',
-        query: {mode: 'test'},
+        query: {mode: 'test', tag: ['one', 'two']},
         body: {ok: true},
         headers: {
           'content-type': 'application/json',
@@ -89,6 +92,7 @@ describe('webhook inbound route', () => {
         },
       },
     });
+    expect(getIntegrationConnectionById).toHaveBeenCalledTimes(1);
   });
 
   it('publishes a form delivery envelope', async () => {
@@ -187,6 +191,7 @@ describe('webhook inbound route', () => {
     expect(res.statusCode).toBe(202);
     const deliveryId = publishIntegrationEventReceived.mock.calls[0]?.[0].event.deliveryId;
     expect(deliveryId).toMatch(UUID_RE);
+    expect(res.json().delivery_id).toBe(deliveryId);
   });
 
   it('rejects an overlong delivery ID header without publishing', async () => {

package/src/presentation/routes/inbound.ts

@@ -1,36 +1,39 @@
-import type {Buffer} from 'node:buffer';
 import {randomUUID} from 'node:crypto';
-import formBodyPlugin from '@fastify/formbody';
 import type {
   GetIntegrationConnectionByIdFn,
   IntegrationTx,
   PublishIntegrationEventReceivedFn,
 } from '@shipfox/api-integration-core-dto';
-import {WEBHOOK_PROVIDER, WEBHOOK_RECEIVED_EVENT} from '@shipfox/api-integration-webhook-dto';
+import {
+  createStoredWebhookRequest,
+  type StoredWebhookRequest,
+  WEBHOOK_MAX_RAW_BODY_BYTES,
+} from '@shipfox/api-integration-core-dto';
+import {WEBHOOK_PROVIDER} from '@shipfox/api-integration-webhook-dto';
 import {ClientError, defineRoute, type RouteGroup} from '@shipfox/node-fastify';
 import type {FastifyPluginAsync} from 'fastify';
 import fp from 'fastify-plugin';
 import {z} from 'zod';
-import {redactHeaders, WEBHOOK_INBOUND_BODY_LIMIT} from '#constants.js';
+import {WEBHOOK_ACCEPTED_CONTENT_TYPES, WEBHOOK_INBOUND_BODY_LIMIT} from '#constants.js';
+import {
+  createGenericWebhookProcessor,
+  type GenericWebhookProcessor,
+} from '#core/webhook-processor.js';
 
 const MAX_DELIVERY_ID_HEADER_LENGTH = 200;
-const acceptedContentTypes = new Set([
-  'application/json',
-  'application/x-www-form-urlencoded',
-  'text/plain',
-]);
-const FORM_URLENCODED_CONTENT_TYPE_RE = /^application\/x-www-form-urlencoded(?:;.*)?$/i;
-
-const formBodyRoutePlugin: FastifyPluginAsync = fp(async (app) => {
-  await app.register(formBodyPlugin, {bodyLimit: WEBHOOK_INBOUND_BODY_LIMIT});
-
-  app.addContentTypeParser(
-    FORM_URLENCODED_CONTENT_TYPE_RE,
-    {parseAs: 'buffer', bodyLimit: WEBHOOK_INBOUND_BODY_LIMIT},
-    (_request, body: Buffer, done) => {
-      done(null, Object.fromEntries(new URLSearchParams(body.toString('utf8'))));
-    },
-  );
+const acceptedContentTypes = new Set<string>(WEBHOOK_ACCEPTED_CONTENT_TYPES);
+const rawWebhookBodyPlugin: FastifyPluginAsync = fp((app) => {
+  app.removeAllContentTypeParsers();
+  for (const contentType of acceptedContentTypes) {
+    app.addContentTypeParser(
+      contentType,
+      {parseAs: 'buffer', bodyLimit: WEBHOOK_INBOUND_BODY_LIMIT},
+      (_request, body, done) => {
+        done(null, body);
+      },
+    );
+  }
+  return Promise.resolve();
 });
 
 export interface CreateWebhookInboundRoutesOptions {
@@ -39,6 +42,7 @@ export interface CreateWebhookInboundRoutesOptions {
   };
   getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
   publishIntegrationEventReceived: PublishIntegrationEventReceivedFn;
+  processor?: GenericWebhookProcessor | undefined;
 }
 
 const inboundParamsSchema = z.object({
@@ -64,7 +68,12 @@ function deliveryIdFor(header: string | string[] | undefined): string {
   return value;
 }
 
+function hasDeliveryId(header: string | string[] | undefined): boolean {
+  return Boolean(Array.isArray(header) ? header[0] : header);
+}
+
 export function createWebhookInboundRoutes(options: CreateWebhookInboundRoutesOptions): RouteGroup {
+  const processor = options.processor ?? createGenericWebhookProcessor(options);
   const inboundRoute = defineRoute({
     method: 'POST',
     path: '/:connectionId',
@@ -94,29 +103,25 @@ export function createWebhookInboundRoutes(options: CreateWebhookInboundRoutesOp
         throw new ClientError('Webhook connection not found', 'not-found', {status: 404});
       }
 
-      const deliveryId = deliveryIdFor(request.headers['x-delivery-id']);
-      const receivedAt = new Date().toISOString();
-      await options.coreDb().transaction(async (tx) => {
-        await options.publishIntegrationEventReceived({
-          tx,
-          event: {
-            provider: WEBHOOK_PROVIDER,
-            source: connection.slug,
-            event: WEBHOOK_RECEIVED_EVENT,
-            workspaceId: connection.workspaceId,
-            connectionId: connection.id,
-            connectionName: connection.displayName,
-            deliveryId,
-            receivedAt,
-            payload: {
-              method: request.method,
-              headers: redactHeaders(request.headers),
-              query: request.query,
-              body: request.body,
-            },
+      const deliveryHeader = request.headers['x-delivery-id'];
+      const deliveryId = deliveryIdFor(deliveryHeader);
+      const result = await processor.process(
+        createGenericStoredWebhookRequest(
+          {
+            body: request.body,
+            connectionId,
+            headers: request.headers,
+            rawQueryString: request.raw.url?.split('?')[1] ?? '',
+            requestId: hasDeliveryId(deliveryHeader) ? randomUUID() : deliveryId,
           },
-        });
-      });
+          new Date().toISOString(),
+        ),
+        connection,
+      );
+
+      if (result.outcome === 'discarded' && result.reason === 'malformed_payload') {
+        throw new ClientError('Malformed webhook payload', 'malformed-payload', {status: 400});
+      }
 
       reply.code(202);
       return {delivery_id: deliveryId};
@@ -126,7 +131,52 @@ export function createWebhookInboundRoutes(options: CreateWebhookInboundRoutesOp
   return {
     prefix: '/webhook',
     auth: [],
-    plugins: [formBodyRoutePlugin],
+    plugins: [rawWebhookBodyPlugin],
     routes: [inboundRoute],
   };
 }
+
+function createGenericStoredWebhookRequest(
+  input: {
+    body: unknown;
+    connectionId: string;
+    headers: Record<string, string | string[] | undefined>;
+    rawQueryString: string;
+    requestId: string;
+  },
+  receivedAt: string,
+): StoredWebhookRequest {
+  if (!(input.body instanceof Uint8Array)) {
+    throw new ClientError('Expected raw webhook body', 'invalid-webhook-request', {status: 400});
+  }
+  if (input.body.byteLength > WEBHOOK_MAX_RAW_BODY_BYTES) {
+    throw new ClientError('Webhook request body is too large', 'body-too-large', {status: 413});
+  }
+
+  try {
+    return createStoredWebhookRequest({
+      requestId: input.requestId,
+      routeId: 'webhook.connection',
+      receivedAt,
+      rawQueryString: input.rawQueryString,
+      headers: webhookHeaders(input.headers),
+      body: input.body,
+      connectionId: input.connectionId,
+    });
+  } catch (error) {
+    throw new ClientError('Webhook request metadata is invalid', 'invalid-webhook-request', {
+      cause: error,
+    });
+  }
+}
+
+function webhookHeaders(
+  headers: Record<string, string | string[] | undefined>,
+): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(headers).flatMap(([name, value]) => {
+      if (value === undefined) return [];
+      return [[name.toLowerCase(), Array.isArray(value) ? value.join(', ') : value]];
+    }),
+  );
+}