@open-mercato/webhooks 0.6.7-develop.6726.1.983ae8a07e → 0.6.7-develop.6749.1.6b54c56dfe

package/src/modules/webhooks/api/inbound/[endpointId]/route.ts

@@ -6,11 +6,31 @@ import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { checkRateLimit, getClientIp, RATE_LIMIT_ERROR_FALLBACK, RATE_LIMIT_ERROR_KEY } from '@open-mercato/shared/lib/ratelimit/helpers'
 import type { RateLimiterService } from '@open-mercato/shared/lib/ratelimit/service'
+import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import type { InboundWebhookRequest } from '@open-mercato/shared/lib/webhooks'
 import { emitWebhooksEvent } from '../../../events'
 import { getWebhookEndpointAdapter } from '../../../lib/adapter-registry'
+import { getWebhookSource } from '../../../lib/inbound-registry'
+import { enqueueInboundDispatch } from '../../../lib/queue'
 import { isWebhookIntegrationEnabled, WEBHOOK_INTEGRATION_DISABLED_MESSAGE } from '../../../lib/integration-state'
 import { json } from '../../helpers'
-import { WebhookInboundReceiptEntity } from '../../../data/entities'
+import { InboundEndpointConfigEntity, WebhookIngestionEntity, WebhookInboundReceiptEntity } from '../../../data/entities'
+
+type IntegrationCredentialsService = {
+  resolve: (
+    integrationId: string,
+    scope: { organizationId: string; tenantId: string },
+  ) => Promise<Record<string, unknown> | null>
+}
+
+function toStringCredentials(credentials: Record<string, unknown> | null): Record<string, string> {
+  const result: Record<string, string> = {}
+  if (!credentials) return result
+  for (const [key, value] of Object.entries(credentials)) {
+    if (typeof value === 'string') result[key] = value
+  }
+  return result
+}
 
 export const metadata = {
   POST: { requireAuth: false },
@@ -29,10 +49,11 @@ const errorSchema = z.object({ error: z.string() })
 
 export async function POST(request: Request, context: RouteContext): Promise<Response> {
   const params = await context.params
-  const adapter = getWebhookEndpointAdapter(params.endpointId)
+  const source = getWebhookSource(params.endpointId)
+  const adapter = source ? undefined : getWebhookEndpointAdapter(params.endpointId)
   const { translate } = await resolveTranslations()
 
-  if (!adapter) {
+  if (!source && !adapter) {
     return json({ error: 'Webhook endpoint not found' }, { status: 404 })
   }
 
@@ -51,6 +72,116 @@ export async function POST(request: Request, context: RouteContext): Promise<Res
     if (rateLimitResponse) return rateLimitResponse
   }
 
+  if (source) {
+    const rawBody = await request.text()
+    const sourceHeaders = Object.fromEntries(request.headers.entries())
+    let parsedBody: Record<string, unknown> = {}
+    try {
+      const parsed = JSON.parse(rawBody)
+      if (parsed && typeof parsed === 'object') parsedBody = parsed as Record<string, unknown>
+    } catch {
+      parsedBody = {}
+    }
+    const inboundRequest: InboundWebhookRequest = { body: rawBody, headers: sourceHeaders, parsedBody }
+
+    const credentialsService = tryResolve<IntegrationCredentialsService>(container, 'integrationCredentialsService')
+    const configs = await findWithDecryption(
+      em,
+      InboundEndpointConfigEntity,
+      { sourceKey: params.endpointId, isActive: true },
+      {},
+    )
+
+    let verifiedScope: { organizationId: string; tenantId: string } | null = null
+    for (const config of configs) {
+      const scope = { organizationId: config.organizationId, tenantId: config.tenantId }
+      const credentials = credentialsService
+        ? await credentialsService.resolve(`webhook_source_${params.endpointId}`, scope)
+        : null
+      let valid = false
+      try {
+        valid = await source.verifier(inboundRequest, toStringCredentials(credentials))
+      } catch {
+        valid = false
+      }
+      if (valid) {
+        verifiedScope = scope
+        break
+      }
+    }
+
+    if (!verifiedScope) {
+      return json({ error: 'Signature verification failed' }, { status: 401 })
+    }
+
+    const eventType = source.eventTypeExtractor(parsedBody, sourceHeaders)
+    const messageId = source.messageIdExtractor?.(parsedBody, sourceHeaders)
+      ?? resolveInboundReceiptMessageId({
+        endpointId: params.endpointId,
+        providerKey: params.endpointId,
+        headers: sourceHeaders,
+        body: rawBody,
+      })
+
+    try {
+      em.persist(em.create(WebhookInboundReceiptEntity, {
+        endpointId: params.endpointId,
+        messageId,
+        providerKey: params.endpointId,
+        eventType,
+        tenantId: verifiedScope.tenantId,
+        organizationId: verifiedScope.organizationId,
+        createdAt: new Date(),
+      }))
+      await em.flush()
+    } catch (error) {
+      if (isUniqueViolation(error)) {
+        return json({ ok: true, duplicate: true })
+      }
+      throw error
+    }
+
+    const ingestion = em.create(WebhookIngestionEntity, {
+      sourceKey: params.endpointId,
+      eventType,
+      externalMessageId: messageId,
+      payload: parsedBody,
+      headers: sourceHeaders,
+      status: 'received',
+      handlerCount: 0,
+      organizationId: verifiedScope.organizationId,
+      tenantId: verifiedScope.tenantId,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    })
+    em.persist(ingestion)
+    await em.flush()
+
+    await enqueueInboundDispatch({
+      ingestionId: ingestion.id,
+      sourceKey: params.endpointId,
+      eventType,
+      tenantId: verifiedScope.tenantId,
+      organizationId: verifiedScope.organizationId,
+    })
+
+    await emitWebhooksEvent('webhooks.inbound.received', {
+      providerKey: params.endpointId,
+      endpointId: params.endpointId,
+      messageId,
+      eventType,
+      payload: parsedBody,
+      tenantId: verifiedScope.tenantId,
+      organizationId: verifiedScope.organizationId,
+    }, { persistent: true })
+
+    return json({ ok: true })
+  }
+
+  if (!adapter) {
+    return json({ error: 'Webhook endpoint not found' }, { status: 404 })
+  }
+
   const body = await request.text()
   const headers = Object.fromEntries(request.headers.entries())
   let verified: Awaited<ReturnType<typeof adapter.verifyWebhook>>
@@ -126,11 +257,12 @@ export const openApi: OpenApiRouteDoc = {
   methods: {
     POST: {
       summary: 'Receive inbound webhook',
-      description: 'Endpoint ids currently resolve to registered adapter provider keys.',
+      description: 'The endpoint id resolves to a registered webhook source first (module-level handler dispatch), otherwise to a legacy adapter provider key.',
       pathParams: z.object({ endpointId: z.string().min(1) }),
       responses: [{ status: 200, description: 'Inbound webhook accepted', schema: inboundResponseSchema }],
       errors: [
         { status: 400, description: 'Verification failed', schema: errorSchema },
+        { status: 401, description: 'Signature verification failed (source flow)', schema: errorSchema },
         { status: 404, description: 'Endpoint not found', schema: errorSchema },
         { status: 429, description: 'Rate limit exceeded', schema: errorSchema },
         { status: 503, description: 'Webhook integration disabled', schema: errorSchema },

package/src/modules/webhooks/data/entities.ts

@@ -1,4 +1,5 @@
 import { Entity, Index, PrimaryKey, Property, Unique } from '@mikro-orm/decorators/legacy'
+import type { WebhookHandlerResult, WebhookIngestionStatus } from '@open-mercato/shared/lib/webhooks'
 
 @Entity({ tableName: 'webhooks' })
 @Index({ properties: ['organizationId', 'tenantId', 'isActive'] })
@@ -184,3 +185,86 @@ export class WebhookInboundReceiptEntity {
   @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
   createdAt: Date = new Date()
 }
+
+@Entity({ tableName: 'webhook_ingestions' })
+@Index({ properties: ['sourceKey', 'status', 'createdAt'] })
+@Index({ properties: ['organizationId', 'tenantId', 'createdAt'] })
+@Index({ properties: ['externalMessageId'] })
+export class WebhookIngestionEntity {
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'source_key', type: 'text' })
+  sourceKey!: string
+
+  @Property({ name: 'event_type', type: 'text' })
+  eventType!: string
+
+  @Property({ name: 'external_message_id', type: 'text', nullable: true })
+  externalMessageId?: string | null
+
+  @Property({ name: 'payload', type: 'json' })
+  payload!: Record<string, unknown>
+
+  @Property({ name: 'headers', type: 'json', nullable: true })
+  headers?: Record<string, string> | null
+
+  @Property({ name: 'status', type: 'text', default: 'received' })
+  status: WebhookIngestionStatus = 'received'
+
+  @Property({ name: 'error_message', type: 'text', nullable: true })
+  errorMessage?: string | null
+
+  @Property({ name: 'processed_at', type: Date, nullable: true })
+  processedAt?: Date | null
+
+  @Property({ name: 'handler_count', type: 'int', default: 0 })
+  handlerCount: number = 0
+
+  @Property({ name: 'handler_results', type: 'json', nullable: true })
+  handlerResults?: WebhookHandlerResult[] | null
+
+  @Property({ name: 'duration_ms', type: 'int', nullable: true })
+  durationMs?: number | null
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+}
+
+@Entity({ tableName: 'webhook_inbound_configs' })
+@Unique({ name: 'webhook_inbound_configs_source_scope_unique', properties: ['sourceKey', 'organizationId', 'tenantId'] })
+@Index({ properties: ['sourceKey', 'isActive'] })
+export class InboundEndpointConfigEntity {
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'source_key', type: 'text' })
+  sourceKey!: string
+
+  @Property({ name: 'is_active', type: 'boolean', default: true })
+  isActive: boolean = true
+
+  @Property({ name: 'integration_id', type: 'text', nullable: true })
+  integrationId?: string | null
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+}

package/src/modules/webhooks/encryption.ts

@@ -8,6 +8,13 @@ export const defaultEncryptionMaps: ModuleEncryptionMap[] = [
       { field: 'previous_secret' },
     ],
   },
+  {
+    entityId: 'webhooks:webhook_ingestion_entity',
+    fields: [
+      { field: 'payload' },
+      { field: 'headers' },
+    ],
+  },
 ]
 
 export default defaultEncryptionMaps

package/src/modules/webhooks/events.ts

@@ -10,6 +10,8 @@ const events = [
   { id: 'webhooks.delivery.exhausted', label: 'Webhook Delivery Retries Exhausted', entity: 'delivery', category: 'lifecycle' as const, clientBroadcast: true },
   { id: 'webhooks.webhook.disabled', label: 'Webhook Auto-Disabled', entity: 'webhook', category: 'lifecycle' as const, clientBroadcast: true },
   { id: 'webhooks.inbound.received', label: 'Inbound Webhook Received', entity: 'inbound', category: 'custom' as const },
+  { id: 'webhooks.inbound.processed', label: 'Inbound Webhook Processed', entity: 'inbound', category: 'lifecycle' as const },
+  { id: 'webhooks.inbound.handler_failed', label: 'Inbound Handler Failed', entity: 'inbound', category: 'lifecycle' as const, clientBroadcast: true },
   { id: 'webhooks.secret.rotated', label: 'Webhook Secret Rotated', entity: 'webhook', category: 'lifecycle' as const },
 ] as const
 

package/src/modules/webhooks/generators.ts

@@ -0,0 +1,57 @@
+import type { GeneratorPlugin } from '@open-mercato/shared/modules/generators'
+
+function buildSourcesOutput({ importSection, entriesLiteral }: { importSection: string; entriesLiteral: string }): string {
+  return `// AUTO-GENERATED by mercato generate registry
+import type { WebhookSourceConfig } from '@open-mercato/shared/lib/webhooks'
+${importSection ? `${importSection}\n` : ''}type WebhookSourceModuleEntry = { moduleId: string; sources: WebhookSourceConfig[] }
+
+export const webhookSourceEntries: WebhookSourceModuleEntry[] = [
+${entriesLiteral ? `  ${entriesLiteral}\n` : ''}]
+`
+}
+
+function buildHandlersOutput({ importSection, entriesLiteral }: { importSection: string; entriesLiteral: string }): string {
+  return `// AUTO-GENERATED by mercato generate registry
+import type { WebhookHandlerRegistryEntry } from '@open-mercato/shared/lib/webhooks'
+${importSection ? `${importSection}\n` : ''}type WebhookHandlerModuleEntry = { moduleId: string; handlers: WebhookHandlerRegistryEntry[] }
+
+export const webhookHandlerEntries: WebhookHandlerModuleEntry[] = [
+${entriesLiteral ? `  ${entriesLiteral}\n` : ''}]
+`
+}
+
+const sourcesPlugin: GeneratorPlugin = {
+  id: 'webhooks.sources',
+  conventionFile: 'webhook-sources.ts',
+  importPrefix: 'WEBHOOK_SOURCES',
+  configExpr: (importName: string, moduleId: string) =>
+    `{ moduleId: '${moduleId}', sources: ((${importName}.default ?? ${importName}.webhookSources ?? []) as WebhookSourceConfig[]) }`,
+  outputFileName: 'webhook-sources.generated.ts',
+  buildOutput: buildSourcesOutput,
+  bootstrapRegistration: {
+    entriesExportName: 'webhookSourceEntries',
+    registrationImports: [
+      `import { registerWebhookSourceEntries } from '@open-mercato/webhooks/modules/webhooks/lib/module-webhook-registry'`,
+    ],
+    buildCall: (name: string) => `registerWebhookSourceEntries(${name})`,
+  },
+}
+
+const handlersPlugin: GeneratorPlugin = {
+  id: 'webhooks.handlers',
+  conventionFile: 'webhook-handlers.ts',
+  importPrefix: 'WEBHOOK_HANDLERS',
+  configExpr: (importName: string, moduleId: string) =>
+    `{ moduleId: '${moduleId}', handlers: ((${importName}.default ?? ${importName}.webhookHandlers ?? []) as WebhookHandlerRegistryEntry[]) }`,
+  outputFileName: 'webhook-handlers.generated.ts',
+  buildOutput: buildHandlersOutput,
+  bootstrapRegistration: {
+    entriesExportName: 'webhookHandlerEntries',
+    registrationImports: [
+      `import { registerWebhookHandlerEntries } from '@open-mercato/webhooks/modules/webhooks/lib/module-webhook-registry'`,
+    ],
+    buildCall: (name: string) => `registerWebhookHandlerEntries(${name})`,
+  },
+}
+
+export const generatorPlugins: GeneratorPlugin[] = [sourcesPlugin, handlersPlugin]

package/src/modules/webhooks/lib/__tests__/inbound-dispatch.test.ts

@@ -0,0 +1,186 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { WebhookHandlerContext, WebhookHandlerPayload } from '@open-mercato/shared/lib/webhooks'
+
+const findOneWithDecryption = jest.fn()
+const emitWebhooksEvent = jest.fn(async () => undefined)
+
+jest.mock('@open-mercato/shared/lib/encryption/find', () => ({
+  findOneWithDecryption: (...args: unknown[]) => findOneWithDecryption(...args),
+}))
+jest.mock('../../events', () => ({
+  emitWebhooksEvent: (...args: unknown[]) => emitWebhooksEvent(...args),
+}))
+
+import { processInboundDispatchJob, type InboundDispatchJob } from '../inbound-dispatch'
+import {
+  clearWebhookHandlers,
+  registerWebhookHandler,
+} from '../inbound-registry'
+
+type IngestionRow = {
+  id: string
+  status: string
+  payload: Record<string, unknown>
+  headers: Record<string, string> | null
+  handlerCount: number
+  handlerResults: unknown
+  processedAt: Date | null
+  durationMs: number | null
+  errorMessage: string | null
+  tenantId: string
+  organizationId: string
+}
+
+function makeIngestion(overrides: Partial<IngestionRow> = {}): IngestionRow {
+  return {
+    id: 'ing-1',
+    status: 'received',
+    payload: { id: 'evt_1', type: 'payment_intent.succeeded' },
+    headers: { 'stripe-signature': 'sig' },
+    handlerCount: 0,
+    handlerResults: null,
+    processedAt: null,
+    durationMs: null,
+    errorMessage: null,
+    tenantId: 't1',
+    organizationId: 'o1',
+    ...overrides,
+  }
+}
+
+const job: InboundDispatchJob = {
+  ingestionId: 'ing-1',
+  sourceKey: 'stripe',
+  eventType: 'payment_intent.succeeded',
+  tenantId: 't1',
+  organizationId: 'o1',
+}
+
+const em = { flush: jest.fn(async () => undefined) } as unknown as EntityManager
+const ctx: WebhookHandlerContext = { resolve: <T,>() => undefined as T }
+
+beforeEach(() => {
+  clearWebhookHandlers()
+  findOneWithDecryption.mockReset()
+  emitWebhooksEvent.mockClear()
+  ;(em.flush as jest.Mock).mockClear()
+})
+
+it('runs all matching handlers and marks the ingestion processed', async () => {
+  const ingestion = makeIngestion()
+  findOneWithDecryption.mockResolvedValue(ingestion)
+  const calls: string[] = []
+  registerWebhookHandler({
+    meta: { source: 'stripe', event: 'payment_intent.*', id: 'payments:a' },
+    handler: async () => ({ default: async () => { calls.push('a') } }),
+  })
+  registerWebhookHandler({
+    meta: { source: 'stripe', event: '*', id: 'audit:b' },
+    handler: async () => ({ default: async () => { calls.push('b') } }),
+  })
+
+  await processInboundDispatchJob(em, job, ctx)
+
+  expect(calls.sort()).toEqual(['a', 'b'])
+  expect(ingestion.status).toBe('processed')
+  expect(ingestion.handlerCount).toBe(2)
+  expect(emitWebhooksEvent).toHaveBeenCalledWith(
+    'webhooks.inbound.processed',
+    expect.objectContaining({ ingestionId: 'ing-1', handlerCount: 2, failedCount: 0 }),
+  )
+})
+
+it('isolates a failing handler, marks failed, and still runs the others', async () => {
+  const ingestion = makeIngestion()
+  findOneWithDecryption.mockResolvedValue(ingestion)
+  const calls: string[] = []
+  registerWebhookHandler({
+    meta: { source: 'stripe', event: 'payment_intent.succeeded', id: 'payments:boom' },
+    handler: async () => ({ default: async () => { throw new Error('handler exploded') } }),
+  })
+  registerWebhookHandler({
+    meta: { source: 'stripe', event: '*', id: 'audit:ok' },
+    handler: async () => ({ default: async () => { calls.push('ok') } }),
+  })
+
+  await processInboundDispatchJob(em, job, ctx)
+
+  expect(calls).toEqual(['ok'])
+  expect(ingestion.status).toBe('failed')
+  expect(ingestion.errorMessage).toBe('1/2 handlers failed')
+  expect(emitWebhooksEvent).toHaveBeenCalledWith(
+    'webhooks.inbound.handler_failed',
+    expect.objectContaining({ handlerId: 'payments:boom', errorMessage: 'handler exploded' }),
+  )
+})
+
+it('is idempotent when the ingestion is already processed', async () => {
+  findOneWithDecryption.mockResolvedValue(makeIngestion({ status: 'processed' }))
+  const handler = jest.fn(async () => ({ default: async () => undefined }))
+  registerWebhookHandler({ meta: { source: 'stripe', event: '*', id: 'x' }, handler })
+
+  await processInboundDispatchJob(em, job, ctx)
+
+  expect(handler).not.toHaveBeenCalled()
+  expect(em.flush).not.toHaveBeenCalled()
+  expect(emitWebhooksEvent).not.toHaveBeenCalled()
+})
+
+it('returns early when the ingestion is missing', async () => {
+  findOneWithDecryption.mockResolvedValue(null)
+  await processInboundDispatchJob(em, job, ctx)
+  expect(em.flush).not.toHaveBeenCalled()
+})
+
+it('passes the handler the payload and headers from the ingestion, not from the job', async () => {
+  const ingestion = makeIngestion({
+    payload: { id: 'evt_from_row', type: 'payment_intent.succeeded' },
+    headers: { 'stripe-signature': 'sig_from_row' },
+  })
+  findOneWithDecryption.mockResolvedValue(ingestion)
+  const seen: WebhookHandlerPayload[] = []
+  registerWebhookHandler({
+    meta: { source: 'stripe', event: '*', id: 'audit:capture' },
+    handler: async () => ({ default: async (payload: WebhookHandlerPayload) => { seen.push(payload) } }),
+  })
+
+  await processInboundDispatchJob(em, job, ctx)
+
+  expect(seen).toHaveLength(1)
+  expect(seen[0].data).toEqual({ id: 'evt_from_row', type: 'payment_intent.succeeded' })
+  expect(seen[0].headers).toEqual({ 'stripe-signature': 'sig_from_row' })
+})
+
+it('re-runs only the handlers that did not already succeed when retried after a partial failure', async () => {
+  const ingestion = makeIngestion({
+    status: 'failed',
+    handlerCount: 2,
+    errorMessage: '1/2 handlers failed',
+    handlerResults: [
+      { handlerId: 'audit:ok', module: 'audit', status: 'success', durationMs: 3, startedAt: '2026-06-17T00:00:00.000Z' },
+      { handlerId: 'payments:boom', module: 'payments', status: 'failed', errorMessage: 'handler exploded', durationMs: 1, startedAt: '2026-06-17T00:00:00.000Z' },
+    ],
+  })
+  findOneWithDecryption.mockResolvedValue(ingestion)
+  const calls: string[] = []
+  registerWebhookHandler({
+    meta: { source: 'stripe', event: '*', id: 'audit:ok' },
+    handler: async () => ({ default: async () => { calls.push('audit:ok') } }),
+  })
+  registerWebhookHandler({
+    meta: { source: 'stripe', event: 'payment_intent.succeeded', id: 'payments:boom' },
+    handler: async () => ({ default: async () => { calls.push('payments:boom') } }),
+  })
+
+  await processInboundDispatchJob(em, job, ctx)
+
+  expect(calls).toEqual(['payments:boom'])
+  expect(ingestion.status).toBe('processed')
+  expect(ingestion.errorMessage).toBeNull()
+  expect(ingestion.handlerResults).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({ handlerId: 'audit:ok', status: 'success' }),
+      expect.objectContaining({ handlerId: 'payments:boom', status: 'success' }),
+    ]),
+  )
+})

package/src/modules/webhooks/lib/__tests__/inbound-registry.test.ts

@@ -0,0 +1,102 @@
+import type {
+  WebhookHandler,
+  WebhookHandlerRegistryEntry,
+  WebhookSourceConfig,
+} from '@open-mercato/shared/lib/webhooks'
+import {
+  clearWebhookHandlers,
+  clearWebhookSources,
+  getWebhookSource,
+  listWebhookHandlers,
+  listWebhookSources,
+  registerWebhookHandler,
+  registerWebhookSource,
+  resolveWebhookHandlers,
+  setWebhookHandlers,
+  setWebhookSources,
+} from '../inbound-registry'
+
+const noopHandler: WebhookHandler = async () => undefined
+
+function makeSource(key: string): WebhookSourceConfig {
+  return {
+    key,
+    label: key,
+    verifier: async () => true,
+    eventTypeExtractor: (body) => String((body as { type?: string }).type ?? ''),
+  }
+}
+
+function makeEntry(source: string, event: string, id: string): WebhookHandlerRegistryEntry {
+  return {
+    meta: { source, event, id },
+    handler: async () => ({ default: noopHandler }),
+  }
+}
+
+beforeEach(() => {
+  clearWebhookSources()
+  clearWebhookHandlers()
+})
+
+describe('webhook source registry', () => {
+  it('registers and resolves a source by key', () => {
+    registerWebhookSource(makeSource('stripe'))
+    expect(getWebhookSource('stripe')?.key).toBe('stripe')
+    expect(getWebhookSource('missing')).toBeUndefined()
+    expect(listWebhookSources()).toHaveLength(1)
+  })
+
+  it('unregister removes only the matching source instance', () => {
+    const unregister = registerWebhookSource(makeSource('stripe'))
+    registerWebhookSource(makeSource('resend'))
+    unregister()
+    expect(getWebhookSource('stripe')).toBeUndefined()
+    expect(getWebhookSource('resend')?.key).toBe('resend')
+  })
+
+  it('setWebhookSources replaces the whole registry', () => {
+    registerWebhookSource(makeSource('old'))
+    setWebhookSources([makeSource('stripe'), makeSource('resend')])
+    expect(getWebhookSource('old')).toBeUndefined()
+    expect(listWebhookSources().map((s) => s.key).sort()).toEqual(['resend', 'stripe'])
+  })
+})
+
+describe('resolveWebhookHandlers', () => {
+  it('matches handlers by source key', () => {
+    registerWebhookHandler(makeEntry('stripe', '*', 'a'))
+    registerWebhookHandler(makeEntry('resend', '*', 'b'))
+    const matched = resolveWebhookHandlers('stripe', 'payment_intent.succeeded')
+    expect(matched.map((m) => m.meta.id)).toEqual(['a'])
+  })
+
+  it('supports exact, wildcard, and prefix-wildcard event patterns', () => {
+    registerWebhookHandler(makeEntry('stripe', 'payment_intent.succeeded', 'exact'))
+    registerWebhookHandler(makeEntry('stripe', 'payment_intent.*', 'prefix'))
+    registerWebhookHandler(makeEntry('stripe', '*', 'all'))
+    registerWebhookHandler(makeEntry('stripe', 'charge.refunded', 'other'))
+
+    const matched = resolveWebhookHandlers('stripe', 'payment_intent.succeeded')
+    expect(matched.map((m) => m.meta.id).sort()).toEqual(['all', 'exact', 'prefix'])
+  })
+
+  it('returns multiple handlers for the same source + event', () => {
+    registerWebhookHandler(makeEntry('stripe', 'payment_intent.succeeded', 'h1'))
+    registerWebhookHandler(makeEntry('stripe', 'payment_intent.succeeded', 'h2'))
+    expect(resolveWebhookHandlers('stripe', 'payment_intent.succeeded')).toHaveLength(2)
+  })
+
+  it('returns no handlers when nothing matches', () => {
+    registerWebhookHandler(makeEntry('stripe', 'charge.refunded', 'x'))
+    expect(resolveWebhookHandlers('stripe', 'payment_intent.succeeded')).toEqual([])
+    expect(resolveWebhookHandlers('paypal', 'charge.refunded')).toEqual([])
+  })
+
+  it('setWebhookHandlers replaces the whole handler registry', () => {
+    registerWebhookHandler(makeEntry('stripe', '*', 'old'))
+    setWebhookHandlers([makeEntry('resend', 'email.received', 'new')])
+    expect(listWebhookHandlers().map((e) => e.meta.id)).toEqual(['new'])
+    expect(resolveWebhookHandlers('resend', 'email.received').map((e) => e.meta.id)).toEqual(['new'])
+  })
+})