@open-mercato/webhooks 0.4.9-canary-8c762104f0

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

@@ -0,0 +1,157 @@
+import { Entity, PrimaryKey, Property, Index } from '@mikro-orm/core'
+
+@Entity({ tableName: 'webhooks' })
+@Index({ properties: ['organizationId', 'tenantId', 'isActive'] })
+@Index({ properties: ['organizationId', 'tenantId', 'deletedAt'] })
+export class WebhookEntity {
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ type: 'text' })
+  name!: string
+
+  @Property({ name: 'description', type: 'text', nullable: true })
+  description?: string | null
+
+  @Property({ name: 'url', type: 'text' })
+  url!: string
+
+  @Property({ name: 'secret', type: 'text' })
+  secret!: string
+
+  @Property({ name: 'previous_secret', type: 'text', nullable: true })
+  previousSecret?: string | null
+
+  @Property({ name: 'previous_secret_set_at', type: Date, nullable: true })
+  previousSecretSetAt?: Date | null
+
+  @Property({ name: 'subscribed_events', type: 'json' })
+  subscribedEvents!: string[]
+
+  @Property({ name: 'http_method', type: 'text', default: "'POST'" })
+  httpMethod: string = 'POST'
+
+  @Property({ name: 'custom_headers', type: 'json', nullable: true })
+  customHeaders?: Record<string, string> | null
+
+  @Property({ name: 'is_active', type: 'boolean', default: true })
+  isActive: boolean = true
+
+  @Property({ name: 'delivery_strategy', type: 'text', default: "'http'" })
+  deliveryStrategy: string = 'http'
+
+  @Property({ name: 'strategy_config', type: 'json', nullable: true })
+  strategyConfig?: Record<string, unknown> | null
+
+  @Property({ name: 'max_retries', type: 'int', default: 10 })
+  maxRetries: number = 10
+
+  @Property({ name: 'timeout_ms', type: 'int', default: 15000 })
+  timeoutMs: number = 15000
+
+  @Property({ name: 'rate_limit_per_minute', type: 'int', default: 0 })
+  rateLimitPerMinute: number = 0
+
+  @Property({ name: 'consecutive_failures', type: 'int', default: 0 })
+  consecutiveFailures: number = 0
+
+  @Property({ name: 'auto_disable_threshold', type: 'int', default: 100 })
+  autoDisableThreshold: number = 100
+
+  @Property({ name: 'last_success_at', type: Date, nullable: true })
+  lastSuccessAt?: Date | null
+
+  @Property({ name: 'last_failure_at', type: Date, nullable: true })
+  lastFailureAt?: Date | null
+
+  @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()
+
+  @Property({ name: 'deleted_at', type: Date, nullable: true })
+  deletedAt?: Date | null
+}
+
+@Entity({ tableName: 'webhook_deliveries' })
+@Index({ properties: ['webhookId', 'status'] })
+@Index({ properties: ['organizationId', 'tenantId', 'createdAt'] })
+@Index({ properties: ['webhookId', 'createdAt'] })
+@Index({ properties: ['eventType', 'organizationId'] })
+export class WebhookDeliveryEntity {
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'webhook_id', type: 'uuid' })
+  webhookId!: string
+
+  @Property({ name: 'event_type', type: 'text' })
+  eventType!: string
+
+  @Property({ name: 'message_id', type: 'text' })
+  messageId!: string
+
+  @Property({ name: 'payload', type: 'json' })
+  payload!: Record<string, unknown>
+
+  @Property({ name: 'status', type: 'text', default: "'pending'" })
+  status: string = 'pending'
+
+  @Property({ name: 'response_status', type: 'int', nullable: true })
+  responseStatus?: number | null
+
+  @Property({ name: 'response_body', type: 'text', nullable: true })
+  responseBody?: string | null
+
+  @Property({ name: 'response_headers', type: 'json', nullable: true })
+  responseHeaders?: Record<string, string> | null
+
+  @Property({ name: 'error_message', type: 'text', nullable: true })
+  errorMessage?: string | null
+
+  @Property({ name: 'attempt_number', type: 'int', default: 0 })
+  attemptNumber: number = 0
+
+  @Property({ name: 'max_attempts', type: 'int', default: 10 })
+  maxAttempts: number = 10
+
+  @Property({ name: 'next_retry_at', type: Date, nullable: true })
+  nextRetryAt?: Date | null
+
+  @Property({ name: 'duration_ms', type: 'int', nullable: true })
+  durationMs?: number | null
+
+  @Property({ name: 'target_url', type: 'text' })
+  targetUrl!: string
+
+  @Property({ name: 'enqueued_at', type: Date })
+  enqueuedAt: Date = new Date()
+
+  @Property({ name: 'last_attempt_at', type: Date, nullable: true })
+  lastAttemptAt?: Date | null
+
+  @Property({ name: 'delivered_at', type: Date, nullable: true })
+  deliveredAt?: Date | 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/data/validators.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod'
+
+export const webhookCreateSchema = z.object({
+  name: z.string().min(1).max(255),
+  description: z.string().max(1000).optional().nullable(),
+  url: z.string().url(),
+  subscribedEvents: z.array(z.string().min(1)).min(1),
+  httpMethod: z.enum(['POST', 'PUT', 'PATCH'] as const).default('POST'),
+  customHeaders: z.record(z.string(), z.string()).optional().nullable(),
+  deliveryStrategy: z.literal('http').default('http'),
+  strategyConfig: z.record(z.string(), z.unknown()).optional().nullable(),
+  maxRetries: z.number().int().min(0).max(30).default(10),
+  timeoutMs: z.number().int().min(1000).max(60000).default(15000),
+  rateLimitPerMinute: z.number().int().min(0).max(10000).default(0),
+  autoDisableThreshold: z.number().int().min(0).max(1000).default(100),
+  integrationId: z.string().optional().nullable(),
+})
+
+export type WebhookCreateInput = z.infer<typeof webhookCreateSchema>
+
+export const webhookUpdateSchema = webhookCreateSchema.partial().extend({
+  isActive: z.boolean().optional(),
+})
+
+export type WebhookUpdateInput = z.infer<typeof webhookUpdateSchema>
+
+export const webhookListQuerySchema = z.object({
+  page: z.string().optional(),
+  pageSize: z.string().optional(),
+  search: z.string().optional(),
+  isActive: z.string().optional(),
+})
+
+export const webhookDeliveryQuerySchema = z.object({
+  page: z.coerce.number().min(1).default(1),
+  pageSize: z.coerce.number().min(1).max(100).default(50),
+  webhookId: z.string().uuid().optional(),
+  eventType: z.string().optional(),
+  status: z.enum(['pending', 'sending', 'delivered', 'failed', 'expired'] as const).optional(),
+})

package/src/modules/webhooks/events.ts

@@ -0,0 +1,15 @@
+import { createModuleEvents } from '@open-mercato/shared/modules/events'
+
+const events = [
+  { id: 'webhooks.webhook.created', label: 'Webhook Created', entity: 'webhook', category: 'crud' as const },
+  { id: 'webhooks.webhook.updated', label: 'Webhook Updated', entity: 'webhook', category: 'crud' as const },
+  { id: 'webhooks.webhook.deleted', label: 'Webhook Deleted', entity: 'webhook', category: 'crud' as const },
+  { id: 'webhooks.delivery.succeeded', label: 'Webhook Delivery Succeeded', entity: 'delivery', category: 'lifecycle' as const },
+  { id: 'webhooks.delivery.failed', label: 'Webhook Delivery Failed', entity: 'delivery', category: 'lifecycle' as const },
+  { id: 'webhooks.webhook.disabled', label: 'Webhook Auto-Disabled', entity: 'webhook', category: 'lifecycle' as const },
+] as const
+
+export const eventsConfig = createModuleEvents({ moduleId: 'webhooks', events })
+export const emitWebhooksEvent = eventsConfig.emit
+export type WebhooksEventId = typeof events[number]['id']
+export default eventsConfig

package/src/modules/webhooks/i18n/en.json

@@ -0,0 +1,73 @@
+{
+  "webhooks.nav.title": "Webhooks",
+  "webhooks.nav.group": "Integrations",
+  "webhooks.nav.create": "Create Webhook",
+
+  "webhooks.list.title": "Webhooks",
+  "webhooks.list.description": "Manage webhook endpoints for receiving platform events.",
+  "webhooks.list.empty": "No webhooks configured yet.",
+  "webhooks.list.createFirst": "Create your first webhook to start receiving event notifications.",
+  "webhooks.list.columns.name": "Name",
+  "webhooks.list.columns.url": "URL",
+  "webhooks.list.columns.events": "Events",
+  "webhooks.list.columns.status": "Status",
+  "webhooks.list.columns.lastTriggered": "Last Triggered",
+  "webhooks.list.columns.successRate": "Health",
+  "webhooks.list.columns.createdAt": "Created",
+  "webhooks.list.status.active": "Active",
+  "webhooks.list.status.inactive": "Inactive",
+  "webhooks.list.actions.edit": "Edit",
+  "webhooks.list.actions.delete": "Delete",
+  "webhooks.list.actions.test": "Test",
+  "webhooks.list.confirmDelete": "Are you sure you want to delete this webhook? This action cannot be undone.",
+  "webhooks.list.deleteSuccess": "Webhook deleted successfully.",
+  "webhooks.list.deleteError": "Failed to delete webhook.",
+
+  "webhooks.form.title.create": "Create Webhook",
+  "webhooks.form.title.edit": "Edit Webhook",
+  "webhooks.form.name": "Name",
+  "webhooks.form.namePlaceholder": "My Webhook",
+  "webhooks.form.description": "Description",
+  "webhooks.form.descriptionPlaceholder": "Optional description for this webhook",
+  "webhooks.form.url": "Endpoint URL",
+  "webhooks.form.urlPlaceholder": "https://example.com/webhook",
+  "webhooks.form.urlHint": "The URL that will receive webhook payloads via HTTP POST.",
+  "webhooks.form.events": "Subscribed Events",
+  "webhooks.form.eventsHint": "Select which events should trigger this webhook.",
+  "webhooks.form.eventsPlaceholder": "Select events...",
+  "webhooks.form.httpMethod": "HTTP Method",
+  "webhooks.form.isActive": "Active",
+  "webhooks.form.maxRetries": "Max Retries",
+  "webhooks.form.maxRetriesHint": "Maximum number of delivery retry attempts (0-30).",
+  "webhooks.form.timeoutMs": "Timeout (ms)",
+  "webhooks.form.timeoutMsHint": "Request timeout in milliseconds (1000-60000).",
+  "webhooks.form.secret": "Signing Secret",
+  "webhooks.form.secretHint": "This secret is used to sign webhook payloads. Keep it safe.",
+  "webhooks.form.secretCopied": "Secret copied to clipboard.",
+  "webhooks.form.group.general": "General",
+  "webhooks.form.group.events": "Event Subscription",
+  "webhooks.form.group.delivery": "Delivery Settings",
+  "webhooks.form.createSuccess": "Webhook created successfully.",
+  "webhooks.form.createError": "Failed to create webhook.",
+  "webhooks.form.updateSuccess": "Webhook updated successfully.",
+  "webhooks.form.updateError": "Failed to update webhook.",
+
+  "webhooks.deliveries.title": "Delivery Log",
+  "webhooks.deliveries.empty": "No delivery attempts yet.",
+  "webhooks.deliveries.columns.event": "Event",
+  "webhooks.deliveries.columns.status": "Status",
+  "webhooks.deliveries.columns.responseStatus": "HTTP Status",
+  "webhooks.deliveries.columns.attempts": "Attempts",
+  "webhooks.deliveries.columns.duration": "Duration",
+  "webhooks.deliveries.columns.createdAt": "Time",
+  "webhooks.deliveries.status.pending": "Pending",
+  "webhooks.deliveries.status.sending": "Sending",
+  "webhooks.deliveries.status.delivered": "Delivered",
+  "webhooks.deliveries.status.failed": "Failed",
+  "webhooks.deliveries.status.expired": "Expired",
+
+  "webhooks.errors.tenantRequired": "Tenant context required.",
+  "webhooks.errors.orgRequired": "Organization context required.",
+  "webhooks.errors.notFound": "Webhook not found.",
+  "webhooks.errors.forbidden": "You do not have permission to perform this action."
+}

package/src/modules/webhooks/index.ts

@@ -0,0 +1,12 @@
+import type { ModuleInfo } from '@open-mercato/shared/modules/registry'
+
+export const metadata: ModuleInfo = {
+  name: 'webhooks',
+  title: 'Webhooks',
+  version: '0.1.0',
+  description: 'Standard Webhooks compliant outbound webhook delivery for platform events.',
+  author: 'Open Mercato Team',
+  license: 'Proprietary',
+}
+
+export { features } from './acl'

package/src/modules/webhooks/setup.ts

@@ -0,0 +1,10 @@
+import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'
+
+export const setup: ModuleSetupConfig = {
+  defaultRoleFeatures: {
+    admin: ['webhooks.*'],
+    employee: ['webhooks.view', 'webhooks.deliveries.view'],
+  },
+}
+
+export default setup

package/src/modules/webhooks/subscribers/outbound-dispatch.ts

@@ -0,0 +1,79 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { WebhookEntity } from '../data/entities'
+import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+
+export const metadata = {
+  event: '*',
+  persistent: true,
+  id: 'webhooks:outbound-dispatch',
+}
+
+export default async function handler(
+  payload: Record<string, unknown>,
+  ctx: { container: { resolve: <T = unknown>(name: string) => T }; eventId?: string },
+) {
+  const eventId = ctx.eventId ?? (payload.eventId as string) ?? (payload.type as string)
+  if (!eventId) return
+
+  const tenantId = payload.tenantId as string | undefined
+  const organizationId = payload.organizationId as string | undefined
+  if (!tenantId) return
+
+  if (eventId.startsWith('webhooks.')) return
+
+  const em = (ctx.container.resolve('em') as EntityManager).fork()
+
+  const webhooks = await findWithDecryption(
+    em,
+    WebhookEntity,
+    {
+      isActive: true,
+      deletedAt: null,
+      tenantId,
+      ...(organizationId ? { organizationId } : {}),
+    },
+    {},
+    { tenantId, organizationId: organizationId ?? '' },
+  )
+
+  if (!webhooks.length) return
+
+  const matchingWebhooks = webhooks.filter((webhook) =>
+    webhook.subscribedEvents.some((pattern) => eventMatchesPattern(eventId, pattern)),
+  )
+
+  if (!matchingWebhooks.length) return
+
+  const queue = ctx.container.resolve<{ enqueueJob: (data: unknown) => Promise<unknown> }>('queueService')
+
+  for (const webhook of matchingWebhooks) {
+    try {
+      await queue.enqueueJob({
+        queue: 'webhook-deliveries',
+        data: {
+          webhookId: webhook.id,
+          eventId,
+          payload,
+          tenantId,
+          organizationId: organizationId ?? webhook.organizationId,
+        },
+      })
+    } catch {
+      // Don't fail the event pipeline if queue is unavailable
+    }
+  }
+}
+
+function eventMatchesPattern(eventId: string, pattern: string): boolean {
+  if (pattern === '*') return true
+  if (pattern === eventId) return true
+  if (pattern.endsWith('.*')) {
+    const prefix = pattern.slice(0, -2)
+    return eventId.startsWith(prefix + '.')
+  }
+  if (pattern.endsWith('*')) {
+    const prefix = pattern.slice(0, -1)
+    return eventId.startsWith(prefix)
+  }
+  return false
+}

package/src/modules/webhooks/workers/webhook-delivery.ts

@@ -0,0 +1,158 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { WebhookEntity, WebhookDeliveryEntity } from '../data/entities'
+import { buildWebhookHeaders, generateMessageId } from '@open-mercato/shared/lib/webhooks'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+
+export const metadata = {
+  queue: 'webhook-deliveries',
+  id: 'webhooks:delivery-worker',
+  concurrency: 10,
+}
+
+interface WebhookDeliveryJob {
+  webhookId: string
+  eventId: string
+  payload: Record<string, unknown>
+  tenantId: string
+  organizationId: string
+}
+
+export default async function handler(
+  job: { data: WebhookDeliveryJob },
+  ctx: { resolve: <T = unknown>(name: string) => T },
+) {
+  const { webhookId, eventId, payload, tenantId, organizationId } = job.data
+  const em = (ctx.resolve('em') as EntityManager).fork()
+
+  const webhook = await findOneWithDecryption(
+    em,
+    WebhookEntity,
+    { id: webhookId, isActive: true, deletedAt: null },
+    {},
+    { tenantId, organizationId },
+  )
+
+  if (!webhook) return
+
+  const messageId = generateMessageId()
+  const timestamp = Math.floor(Date.now() / 1000)
+  const body = JSON.stringify({
+    type: eventId,
+    timestamp: new Date().toISOString(),
+    data: payload,
+  })
+
+  const now = new Date()
+  const delivery = em.create(WebhookDeliveryEntity, {
+    webhookId: webhook.id,
+    eventType: eventId,
+    messageId,
+    payload: JSON.parse(body),
+    status: 'sending',
+    attemptNumber: 0,
+    maxAttempts: webhook.maxRetries,
+    targetUrl: webhook.url,
+    organizationId: webhook.organizationId,
+    tenantId: webhook.tenantId,
+    enqueuedAt: now,
+    createdAt: now,
+    updatedAt: now,
+  })
+
+  await em.flush()
+
+  const headers = buildWebhookHeaders(
+    messageId,
+    timestamp,
+    body,
+    webhook.secret,
+    webhook.previousSecret,
+  )
+
+  const startTime = Date.now()
+
+  try {
+    const controller = new AbortController()
+    const timeoutId = setTimeout(() => controller.abort(), webhook.timeoutMs)
+
+    const response = await fetch(webhook.url, {
+      method: webhook.httpMethod,
+      headers: {
+        'content-type': 'application/json',
+        ...headers,
+        ...(webhook.customHeaders ?? {}),
+      },
+      body,
+      signal: controller.signal,
+    })
+
+    clearTimeout(timeoutId)
+
+    const durationMs = Date.now() - startTime
+    const responseBody = await response.text().catch(() => '')
+
+    delivery.responseStatus = response.status
+    delivery.responseBody = responseBody.slice(0, 4096)
+    delivery.durationMs = durationMs
+    delivery.lastAttemptAt = new Date()
+    delivery.attemptNumber += 1
+
+    if (response.ok) {
+      delivery.status = 'delivered'
+      delivery.deliveredAt = new Date()
+      webhook.consecutiveFailures = 0
+      webhook.lastSuccessAt = new Date()
+    } else {
+      const shouldRetry = shouldRetryStatus(response.status) && delivery.attemptNumber < delivery.maxAttempts
+      if (shouldRetry) {
+        delivery.status = 'pending'
+        delivery.nextRetryAt = calculateNextRetry(delivery.attemptNumber)
+      } else {
+        delivery.status = 'failed'
+      }
+      webhook.consecutiveFailures += 1
+      webhook.lastFailureAt = new Date()
+
+      if (webhook.autoDisableThreshold > 0 && webhook.consecutiveFailures >= webhook.autoDisableThreshold) {
+        webhook.isActive = false
+      }
+    }
+  } catch (error) {
+    const durationMs = Date.now() - startTime
+    delivery.durationMs = durationMs
+    delivery.lastAttemptAt = new Date()
+    delivery.attemptNumber += 1
+    delivery.errorMessage = error instanceof Error ? error.message : 'Unknown error'
+
+    const shouldRetry = delivery.attemptNumber < delivery.maxAttempts
+    if (shouldRetry) {
+      delivery.status = 'pending'
+      delivery.nextRetryAt = calculateNextRetry(delivery.attemptNumber)
+    } else {
+      delivery.status = 'failed'
+    }
+
+    webhook.consecutiveFailures += 1
+    webhook.lastFailureAt = new Date()
+
+    if (webhook.autoDisableThreshold > 0 && webhook.consecutiveFailures >= webhook.autoDisableThreshold) {
+      webhook.isActive = false
+    }
+  }
+
+  await em.flush()
+}
+
+function shouldRetryStatus(status: number): boolean {
+  if (status >= 200 && status < 300) return false
+  if (status === 408 || status === 429) return true
+  if (status >= 500) return true
+  return false
+}
+
+function calculateNextRetry(attemptNumber: number): Date {
+  const baseDelay = 1000
+  const delayMs = baseDelay * Math.pow(2, attemptNumber - 1)
+  const jitter = Math.random() * 1000
+  return new Date(Date.now() + delayMs + jitter)
+}

package/tsconfig.build.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["src/**/__tests__/**/*", "src/**/*.test.ts"]
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/__tests__/**"]
+}

package/watch.mjs

@@ -0,0 +1,6 @@
+import { watch } from '../../scripts/watch.mjs'
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+watch(__dirname)