@open-mercato/webhooks 0.6.5-develop.4534.1.b459babe6d → 0.6.5-develop.4559.1.839e136509

package/src/modules/webhooks/__integration__/TC-WEBHOOK-007.spec.ts

@@ -0,0 +1,102 @@
+import { expect, test } from '@playwright/test';
+import { apiRequest, getAuthToken } from '@open-mercato/core/helpers/integration/api';
+import { getTokenScope } from '@open-mercato/core/helpers/integration/generalFixtures';
+import { createOrganizationInDb, deleteOrganizationInDb } from '@open-mercato/core/helpers/integration/dbFixtures';
+import {
+  cleanupWebhooksUser,
+  createWebhookFixture,
+  deleteWebhookIfExists,
+  listWebhooks,
+  provisionWebhooksUser,
+  type ProvisionedWebhooksUser,
+  type WebhookCreateResponse,
+} from './helpers/fixtures';
+
+/**
+ * TC-WEBHOOK-007: Tenant/organization scoping isolation
+ * Source: https://github.com/open-mercato/open-mercato/issues/2482
+ *
+ * Webhooks are scoped by tenantId + organizationId. Within one tenant, two
+ * organization-restricted users must not see or mutate each other's webhooks:
+ * the list excludes out-of-scope rows and detail/update/delete on a foreign
+ * webhook returns 404 (existence is not revealed across the org boundary).
+ */
+const MANAGE_FEATURES = ['webhooks.view', 'webhooks.manage'];
+
+test.describe('TC-WEBHOOK-007: Tenant/organization scoping isolation', () => {
+  test('should isolate webhooks between organizations within the same tenant', async ({ request }) => {
+    const adminToken = await getAuthToken(request);
+    const { tenantId, organizationId: orgA } = getTokenScope(adminToken);
+
+    let orgB: string | null = null;
+    let userA: ProvisionedWebhooksUser | null = null;
+    let userB: ProvisionedWebhooksUser | null = null;
+    let webhookA: WebhookCreateResponse | null = null;
+    let webhookB: WebhookCreateResponse | null = null;
+
+    try {
+      orgB = await createOrganizationInDb({ name: `TC-WEBHOOK-007 Org B ${Date.now()}`, tenantId });
+
+      userA = await provisionWebhooksUser(request, adminToken, {
+        tenantId,
+        organizationId: orgA,
+        features: MANAGE_FEATURES,
+        organizations: [orgA],
+        slug: 'org-a',
+      });
+      userB = await provisionWebhooksUser(request, adminToken, {
+        tenantId,
+        organizationId: orgB,
+        features: MANAGE_FEATURES,
+        organizations: [orgB],
+        slug: 'org-b',
+      });
+
+      webhookA = await createWebhookFixture(request, userA.token, {
+        name: `TC-WEBHOOK-007 A ${Date.now()}`,
+        url: 'https://example.com/webhook-org-a',
+        subscribedEvents: ['catalog.product.created'],
+      });
+      webhookB = await createWebhookFixture(request, userB.token, {
+        name: `TC-WEBHOOK-007 B ${Date.now()}`,
+        url: 'https://example.com/webhook-org-b',
+        subscribedEvents: ['catalog.product.created'],
+      });
+
+      // Lists are scoped: each user sees only their own organization's webhook.
+      const listA = await listWebhooks(request, userA.token);
+      expect(listA.items.some((item) => item.id === webhookA!.id)).toBe(true);
+      expect(listA.items.some((item) => item.id === webhookB!.id)).toBe(false);
+
+      const listB = await listWebhooks(request, userB.token);
+      expect(listB.items.some((item) => item.id === webhookB!.id)).toBe(true);
+      expect(listB.items.some((item) => item.id === webhookA!.id)).toBe(false);
+
+      // Cross-org reads/writes are not found.
+      const crossGet = await apiRequest(request, 'GET', `/api/webhooks/${webhookB.id}`, { token: userA.token });
+      expect(crossGet.status()).toBe(404);
+
+      const crossUpdate = await apiRequest(request, 'PUT', `/api/webhooks/${webhookB.id}`, {
+        token: userA.token,
+        data: { name: `TC-WEBHOOK-007 cross-org hijack ${Date.now()}` },
+      });
+      expect(crossUpdate.status()).toBe(404);
+
+      const crossDelete = await apiRequest(request, 'DELETE', `/api/webhooks/${webhookB.id}`, { token: userA.token });
+      expect(crossDelete.status()).toBe(404);
+
+      const crossGetReverse = await apiRequest(request, 'GET', `/api/webhooks/${webhookA.id}`, { token: userB.token });
+      expect(crossGetReverse.status()).toBe(404);
+
+      // In-scope access still works after the cross-org attempts.
+      const ownGet = await apiRequest(request, 'GET', `/api/webhooks/${webhookA.id}`, { token: userA.token });
+      expect(ownGet.status()).toBe(200);
+    } finally {
+      await deleteWebhookIfExists(request, userA?.token ?? null, webhookA?.id ?? null);
+      await deleteWebhookIfExists(request, userB?.token ?? null, webhookB?.id ?? null);
+      await cleanupWebhooksUser(request, adminToken, userA);
+      await cleanupWebhooksUser(request, adminToken, userB);
+      await deleteOrganizationInDb(orgB);
+    }
+  });
+});

package/src/modules/webhooks/__integration__/TC-WEBHOOK-008.spec.ts

@@ -0,0 +1,109 @@
+import { expect, test } from '@playwright/test';
+import { apiRequest, getAuthToken } from '@open-mercato/core/helpers/integration/api';
+import {
+  buildMockInboundUrl,
+  createWebhookFixture,
+  deleteWebhookIfExists,
+  listWebhookDeliveries,
+  sendTestDelivery,
+} from './helpers/fixtures';
+
+/**
+ * TC-WEBHOOK-008: Delivery list filtering by status and event type
+ * Source: https://github.com/open-mercato/open-mercato/issues/2482
+ *
+ * GET /api/webhooks/deliveries supports webhookId, status, and eventType filters.
+ * Seeds three deliveries on one webhook — delivered(created), delivered(updated),
+ * expired(created) — then verifies each filter and their intersection.
+ */
+const EVENT_CREATED = 'catalog.product.created';
+const EVENT_UPDATED = 'catalog.product.updated';
+
+function deliveriesPath(webhookId: string, extra: Record<string, string> = {}): string {
+  const params = new URLSearchParams({ webhookId, ...extra });
+  return `/api/webhooks/deliveries?${params.toString()}`;
+}
+
+test.describe('TC-WEBHOOK-008: Delivery list filtering by status and event type', () => {
+  test('should filter delivery logs by status, event type, and their combination', async ({ request }) => {
+    const token = await getAuthToken(request);
+    let webhookId: string | null = null;
+
+    try {
+      const created = await createWebhookFixture(request, token, {
+        name: `Webhook Filter ${Date.now()}`,
+        url: buildMockInboundUrl(),
+        subscribedEvents: [EVENT_CREATED, EVENT_UPDATED],
+        customHeaders: { 'x-mock-webhook-signature': 'valid' },
+      });
+      webhookId = created.id;
+
+      const deliveredCreated = await sendTestDelivery(request, token, created.id, { eventType: EVENT_CREATED });
+      expect(deliveredCreated.delivery.status).toBe('delivered');
+      const deliveredUpdated = await sendTestDelivery(request, token, created.id, { eventType: EVENT_UPDATED });
+      expect(deliveredUpdated.delivery.status).toBe('delivered');
+
+      // Flip the mock signature to invalid so the next attempt fails terminally (expired).
+      const invalidate = await apiRequest(request, 'PUT', `/api/webhooks/${created.id}`, {
+        token,
+        data: { customHeaders: { 'x-mock-webhook-signature': 'invalid' } },
+      });
+      expect(invalidate.status()).toBe(200);
+
+      const expiredCreated = await sendTestDelivery(request, token, created.id, { eventType: EVENT_CREATED });
+      expect(expiredCreated.delivery.status).toBe('expired');
+
+      const d1 = deliveredCreated.delivery.id;
+      const d2 = deliveredUpdated.delivery.id;
+      const d3 = expiredCreated.delivery.id;
+
+      // Unfiltered (by webhook): all three present.
+      const all = await listWebhookDeliveries(request, token, created.id, deliveriesPath(created.id));
+      expect(all.total).toBeGreaterThanOrEqual(3);
+      for (const id of [d1, d2, d3]) {
+        expect(all.items.some((item) => item.id === id)).toBe(true);
+      }
+
+      // status=delivered → d1, d2 only.
+      const delivered = await listWebhookDeliveries(request, token, created.id, deliveriesPath(created.id, { status: 'delivered' }));
+      expect(delivered.items.every((item) => item.status === 'delivered')).toBe(true);
+      expect(delivered.items.some((item) => item.id === d1)).toBe(true);
+      expect(delivered.items.some((item) => item.id === d2)).toBe(true);
+      expect(delivered.items.some((item) => item.id === d3)).toBe(false);
+
+      // status=expired → d3 only.
+      const expired = await listWebhookDeliveries(request, token, created.id, deliveriesPath(created.id, { status: 'expired' }));
+      expect(expired.items.every((item) => item.status === 'expired')).toBe(true);
+      expect(expired.items.some((item) => item.id === d3)).toBe(true);
+      expect(expired.items.some((item) => item.id === d1)).toBe(false);
+
+      // eventType=created → d1, d3 only.
+      const createdEvents = await listWebhookDeliveries(request, token, created.id, deliveriesPath(created.id, { eventType: EVENT_CREATED }));
+      expect(createdEvents.items.every((item) => item.eventType === EVENT_CREATED)).toBe(true);
+      expect(createdEvents.items.some((item) => item.id === d1)).toBe(true);
+      expect(createdEvents.items.some((item) => item.id === d3)).toBe(true);
+      expect(createdEvents.items.some((item) => item.id === d2)).toBe(false);
+
+      // Combined status=delivered & eventType=created → d1 only.
+      const combined = await listWebhookDeliveries(
+        request,
+        token,
+        created.id,
+        deliveriesPath(created.id, { status: 'delivered', eventType: EVENT_CREATED }),
+      );
+      expect(combined.items.every((item) => item.status === 'delivered' && item.eventType === EVENT_CREATED)).toBe(true);
+      expect(combined.items.some((item) => item.id === d1)).toBe(true);
+      expect(combined.items.some((item) => item.id === d2)).toBe(false);
+      expect(combined.items.some((item) => item.id === d3)).toBe(false);
+
+      // Non-matching filter → empty result set with pagination metadata.
+      const empty = await listWebhookDeliveries(request, token, created.id, deliveriesPath(created.id, { status: 'pending' }));
+      expect(empty.items).toEqual([]);
+      expect(empty.total).toBe(0);
+      expect(empty.page).toBe(1);
+      expect(empty.totalPages).toBe(0);
+    } finally {
+      await deleteWebhookIfExists(request, token, webhookId);
+    }
+  });
+});

package/src/modules/webhooks/__integration__/TC-WEBHOOK-009.spec.ts

@@ -0,0 +1,95 @@
+import { expect, test } from '@playwright/test';
+import { apiRequest, getAuthToken } from '@open-mercato/core/helpers/integration/api';
+import { readJsonSafe } from '@open-mercato/core/helpers/integration/generalFixtures';
+import { createWebhookFixture, deleteWebhookIfExists } from './helpers/fixtures';
+
+/**
+ * TC-WEBHOOK-009: Invalid and unsafe URL rejection
+ * Source: https://github.com/open-mercato/open-mercato/issues/2482
+ *
+ * Webhook URLs go through the shared outbound-URL safety check. Forbidden schemes,
+ * embedded credentials, and malformed URLs are rejected with 400 on both create and
+ * update regardless of configuration. Private/loopback hosts are rejected unless the
+ * deployment opts in via OM_WEBHOOKS_ALLOW_PRIVATE_URLS (the integration env enables
+ * it so the loopback mock receiver works) — this spec asserts whichever behavior the
+ * active flag dictates. Exhaustive private-IP coverage lives in the unit suites
+ * (data/__tests__/validators.test.ts, lib/__tests__/url-safety.test.ts).
+ */
+const PRIVATE_URLS_ALLOWED = ['1', 'true', 'yes', 'on'].includes(
+  (process.env.OM_WEBHOOKS_ALLOW_PRIVATE_URLS ?? '').trim().toLowerCase(),
+);
+
+const ALWAYS_UNSAFE_URLS = [
+  'ftp://example.com/webhook',
+  'file:///etc/passwd',
+  'http://user:pass@example.com/webhook',
+  'not-a-valid-url',
+];
+
+const PRIVATE_HOST_URLS = [
+  'http://127.0.0.1:9001/webhook',
+  'http://10.0.0.1/webhook',
+  'http://[::1]:9001/webhook',
+];
+
+function createBody(url: string) {
+  return {
+    name: `Webhook URL Safety ${Date.now()}`,
+    url,
+    subscribedEvents: ['catalog.product.created'],
+  };
+}
+
+test.describe('TC-WEBHOOK-009: Invalid and unsafe URL rejection', () => {
+  test('should reject unsafe webhook URLs on create and update and accept valid external URLs', async ({ request }) => {
+    const token = await getAuthToken(request);
+    let webhookId: string | null = null;
+    const strayPrivateWebhookIds: string[] = [];
+
+    try {
+      // Always-unsafe URLs are rejected at create regardless of the private-URL flag.
+      for (const url of ALWAYS_UNSAFE_URLS) {
+        const response = await apiRequest(request, 'POST', '/api/webhooks', { token, data: createBody(url) });
+        expect(response.status(), `POST should reject unsafe url ${url}`).toBe(400);
+      }
+
+      // A valid external https URL is accepted.
+      const created = await createWebhookFixture(request, token, {
+        name: `Webhook URL Safety Valid ${Date.now()}`,
+        url: 'https://example.com/webhook-url-safety',
+        subscribedEvents: ['catalog.product.created'],
+      });
+      webhookId = created.id;
+
+      // Updating an existing webhook to an unsafe URL is rejected; the record is unchanged.
+      for (const url of ALWAYS_UNSAFE_URLS) {
+        const response = await apiRequest(request, 'PUT', `/api/webhooks/${created.id}`, { token, data: { url } });
+        expect(response.status(), `PUT should reject unsafe url ${url}`).toBe(400);
+      }
+
+      // Updating to another valid external URL succeeds.
+      const validUpdate = await apiRequest(request, 'PUT', `/api/webhooks/${created.id}`, {
+        token,
+        data: { url: 'https://example.org/webhook-url-safety-updated' },
+      });
+      expect(validUpdate.status()).toBe(200);
+
+      // Private/loopback hosts: behavior depends on the deployment flag.
+      for (const url of PRIVATE_HOST_URLS) {
+        const response = await apiRequest(request, 'POST', '/api/webhooks', { token, data: createBody(url) });
+        if (PRIVATE_URLS_ALLOWED) {
+          expect(response.status(), `POST should accept private url ${url} when allowed`).toBe(201);
+          const body = await readJsonSafe<{ id?: string }>(response);
+          if (body?.id) strayPrivateWebhookIds.push(body.id);
+        } else {
+          expect(response.status(), `POST should reject private url ${url} when not allowed`).toBe(400);
+        }
+      }
+    } finally {
+      await deleteWebhookIfExists(request, token, webhookId);
+      for (const id of strayPrivateWebhookIds) {
+        await deleteWebhookIfExists(request, token, id);
+      }
+    }
+  });
+});

package/src/modules/webhooks/__integration__/TC-WEBHOOK-010.spec.ts

@@ -0,0 +1,89 @@
+import { expect, test } from '@playwright/test';
+import { getAuthToken } from '@open-mercato/core/helpers/integration/api';
+import {
+  buildMockInboundUrl,
+  createWebhookFixture,
+  deleteWebhookIfExists,
+  getDeliveryDetail,
+  sendTestDelivery,
+} from './helpers/fixtures';
+
+/**
+ * TC-WEBHOOK-010: Delivery detail response includes full payload and response body
+ * Source: https://github.com/open-mercato/open-mercato/issues/2482
+ *
+ * The delivery detail endpoint must expose the complete sent payload and the full
+ * response captured from the endpoint (status, body, headers) plus attempt/timing
+ * metadata, so admins can debug a delivery end-to-end.
+ */
+const EVENT_TYPE = 'webhooks.test.detail';
+
+test.describe('TC-WEBHOOK-010: Delivery detail full payload and response body', () => {
+  test('should expose the complete payload and response details for a delivery', async ({ request }) => {
+    const token = await getAuthToken(request);
+    let webhookId: string | null = null;
+
+    try {
+      const created = await createWebhookFixture(request, token, {
+        name: `Webhook Detail ${Date.now()}`,
+        url: buildMockInboundUrl(),
+        subscribedEvents: ['catalog.product.created'],
+        customHeaders: { 'x-mock-webhook-signature': 'valid' },
+      });
+      webhookId = created.id;
+
+      const eventData = { sku: 'TEST-123', nested: { value: 42 } };
+
+      const testResult = await sendTestDelivery(request, token, created.id, {
+        eventType: EVENT_TYPE,
+        payload: eventData,
+      });
+      expect(testResult.delivery.status).toBe('delivered');
+      const deliveryId = testResult.delivery.id;
+
+      const detail = await getDeliveryDetail(request, token, deliveryId);
+
+      // Identity + routing
+      expect(detail.id).toBe(deliveryId);
+      expect(detail.webhookId).toBe(created.id);
+      expect(detail.eventType).toBe(EVENT_TYPE);
+      expect(detail.targetUrl).toBe(created.url);
+      expect(typeof detail.messageId).toBe('string');
+      expect(detail.messageId.length).toBeGreaterThan(0);
+
+      // Outcome
+      expect(detail.status).toBe('delivered');
+      expect(detail.responseStatus).toBe(200);
+      expect(detail.errorMessage).toBeNull();
+
+      // The delivery body wraps the event data in the Standard-Webhooks envelope
+      // { type, timestamp, data }; the sent payload is preserved under `data`.
+      expect(detail.payload).toMatchObject({
+        type: EVENT_TYPE,
+        data: { sku: 'TEST-123', nested: { value: 42 } },
+      });
+      const envelopeTimestamp = (detail.payload as { timestamp?: unknown }).timestamp;
+      expect(typeof envelopeTimestamp).toBe('string');
+      expect(Number.isNaN(Date.parse(envelopeTimestamp as string))).toBe(false);
+
+      // Full captured response (the mock receiver replies { ok: true } as JSON)
+      expect(detail.responseBody).toBe(JSON.stringify({ ok: true }));
+      expect(detail.responseHeaders).not.toBeNull();
+      expect(detail.responseHeaders?.['content-type']).toContain('application/json');
+
+      // Attempt + timing metadata
+      expect(detail.attemptNumber).toBeGreaterThanOrEqual(1);
+      expect(detail.maxAttempts).toBeGreaterThanOrEqual(1);
+      expect(typeof detail.durationMs).toBe('number');
+      expect(detail.durationMs as number).toBeGreaterThanOrEqual(0);
+      expect(detail.nextRetryAt).toBeNull();
+
+      for (const timestamp of [detail.createdAt, detail.enqueuedAt, detail.lastAttemptAt, detail.deliveredAt, detail.updatedAt]) {
+        expect(typeof timestamp).toBe('string');
+        expect(Number.isNaN(Date.parse(timestamp as string))).toBe(false);
+      }
+    } finally {
+      await deleteWebhookIfExists(request, token, webhookId);
+    }
+  });
+});

package/src/modules/webhooks/__integration__/helpers/fixtures.ts

@@ -1,6 +1,8 @@
 import { expect, type APIRequestContext } from '@playwright/test';
-import { apiRequest } from '@open-mercato/core/helpers/integration/api';
+import { apiRequest, getAuthToken } from '@open-mercato/core/helpers/integration/api';
 import { expectId, readJsonSafe } from '@open-mercato/core/helpers/integration/generalFixtures';
+import { createUserFixture, deleteUserIfExists } from '@open-mercato/core/helpers/integration/authFixtures';
+import { deleteUserAclInDb, setUserAclInDb } from '@open-mercato/core/helpers/integration/dbFixtures';
 
 const BASE_URL = process.env.BASE_URL?.trim() || 'http://localhost:3000';
 
@@ -247,3 +249,101 @@ export async function deleteWebhookIfExists(
     return;
   }
 }
+
+export type WebhookRotateSecretResponse = {
+  success: true;
+  secret: string;
+  previousSecretSetAt: string | null;
+};
+
+export async function rotateWebhookSecret(
+  request: APIRequestContext,
+  token: string,
+  webhookId: string,
+  path = `/api/webhooks/${webhookId}/rotate-secret`,
+): Promise<WebhookRotateSecretResponse> {
+  const response = await apiRequest(request, 'POST', path, { token });
+  expect(response.status()).toBe(200);
+  const body = await readJsonSafe<WebhookRotateSecretResponse>(response);
+  if (!body) {
+    throw new Error(`Expected rotate-secret response for ${webhookId}`);
+  }
+  return body;
+}
+
+export type WebhookTestDeliveryResponse = {
+  success: true;
+  delivery: WebhookDeliveryDetailResponse;
+};
+
+export async function sendTestDelivery(
+  request: APIRequestContext,
+  token: string,
+  webhookId: string,
+  input: { eventType?: string; payload?: Record<string, unknown> } = {},
+  path = `/api/webhooks/${webhookId}/test`,
+): Promise<WebhookTestDeliveryResponse> {
+  const response = await apiRequest(request, 'POST', path, { token, data: input });
+  expect(response.status()).toBe(200);
+  const body = await readJsonSafe<WebhookTestDeliveryResponse>(response);
+  if (!body) {
+    throw new Error(`Expected test delivery response for ${webhookId}`);
+  }
+  return body;
+}
+
+export type ProvisionedWebhooksUser = {
+  userId: string;
+  email: string;
+  password: string;
+  token: string;
+};
+
+/**
+ * Creates a self-contained, role-less user and grants it an exact webhooks feature
+ * set (and optional organization-visibility list) through a per-user ACL row, then
+ * logs it in. The DB ACL path mirrors the org-scope fixtures: granting features via
+ * the ACL API requires a super-admin actor, while `setUserAclInDb` keeps the spec
+ * self-contained and deterministic. Login happens AFTER the ACL is written so the
+ * fresh session resolves the new grants.
+ */
+export async function provisionWebhooksUser(
+  request: APIRequestContext,
+  adminToken: string,
+  input: {
+    tenantId: string;
+    organizationId: string;
+    features: string[];
+    organizations?: string[] | null;
+    slug: string;
+  },
+): Promise<ProvisionedWebhooksUser> {
+  const unique = `${Date.now()}${Math.floor(Math.random() * 1_000_000)}`;
+  const email = `qa-webhooks-${input.slug}-${unique}@acme.com`;
+  const password = 'Valid1!Webhooks';
+  const userId = await createUserFixture(request, adminToken, {
+    email,
+    password,
+    organizationId: input.organizationId,
+    roles: [],
+    name: `QA Webhooks ${input.slug}`,
+  });
+  await setUserAclInDb({
+    userId,
+    tenantId: input.tenantId,
+    features: input.features,
+    organizations: input.organizations ?? null,
+  });
+  const token = await getAuthToken(request, email, password);
+  return { userId, email, password, token };
+}
+
+export async function cleanupWebhooksUser(
+  request: APIRequestContext,
+  adminToken: string | null,
+  user: ProvisionedWebhooksUser | null,
+): Promise<void> {
+  if (!user) return;
+  await deleteUserAclInDb(user.userId).catch(() => undefined);
+  await deleteUserIfExists(request, adminToken, user.userId).catch(() => undefined);
+}

package/src/modules/webhooks/api/webhooks/[id]/__tests__/optimistic-lock.test.ts

@@ -0,0 +1,101 @@
+/** @jest-environment node */
+
+import { OPTIMISTIC_LOCK_HEADER_NAME } from '@open-mercato/shared/lib/crud/optimistic-lock-headers'
+
+const WEBHOOK_ID = '123e4567-e89b-12d3-a456-426614174070'
+const CURRENT_VERSION = '2026-06-01T10:00:00.000Z'
+const STALE_VERSION = '2026-06-01T09:00:00.000Z'
+
+const webhookRecord = {
+  id: WEBHOOK_ID,
+  name: 'Hook',
+  description: null,
+  url: 'https://example.com/hook',
+  subscribedEvents: ['a.b.c'],
+  httpMethod: 'POST',
+  isActive: true,
+  organizationId: 'org-1',
+  tenantId: 'tenant-1',
+  updatedAt: new Date(CURRENT_VERSION),
+  deletedAt: null as Date | null,
+}
+
+const mockEm = {
+  fork: jest.fn(() => mockEm),
+  flush: jest.fn(async () => undefined),
+}
+
+const mockEmitWebhooksEvent = jest.fn(async () => undefined)
+
+jest.mock('../../../../events', () => ({
+  emitWebhooksEvent: (...args: unknown[]) => mockEmitWebhooksEvent(...args),
+}))
+
+jest.mock('../../../helpers', () => ({
+  json: (payload: unknown, init: ResponseInit = { status: 200 }) =>
+    new Response(JSON.stringify(payload), {
+      ...init,
+      headers: { 'content-type': 'application/json' },
+    }),
+  resolveWebhookRequestScope: jest.fn(async () => ({ em: mockEm, tenantId: 'tenant-1', organizationId: 'org-1' })),
+  findScopedWebhook: jest.fn(async () => (webhookRecord.deletedAt ? null : webhookRecord)),
+  serializeWebhookDetail: (item: { id: string; updatedAt: Date }) => ({
+    id: item.id,
+    updatedAt: item.updatedAt.toISOString(),
+  }),
+}))
+
+jest.mock('@open-mercato/shared/lib/i18n/server', () => ({
+  resolveTranslations: jest.fn(async () => ({ translate: (_key: string, fallback?: string) => fallback ?? '' })),
+}))
+
+import { PUT, DELETE } from '../route'
+
+function request(method: string, headerVersion: string | null, body?: unknown) {
+  const headers: Record<string, string> = { 'content-type': 'application/json' }
+  if (headerVersion) headers[OPTIMISTIC_LOCK_HEADER_NAME] = headerVersion
+  return new Request(`http://localhost/api/webhooks/${WEBHOOK_ID}`, {
+    method,
+    headers,
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  })
+}
+
+const context = { params: Promise.resolve({ id: WEBHOOK_ID }) }
+
+describe('webhook endpoint PUT/DELETE optimistic locking', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+    webhookRecord.deletedAt = null
+    delete process.env.OM_OPTIMISTIC_LOCK
+  })
+
+  it('PUT returns 409 with the structured conflict body when the expected version is stale', async () => {
+    const res = await PUT(request('PUT', STALE_VERSION, { name: 'X' }), context)
+    expect(res.status).toBe(409)
+    const body = await res.json()
+    expect(body.code).toBe('optimistic_lock_conflict')
+    expect(body.currentUpdatedAt).toBe(CURRENT_VERSION)
+    expect(mockEm.flush).not.toHaveBeenCalled()
+  })
+
+  it('PUT succeeds when the expected version matches', async () => {
+    const res = await PUT(request('PUT', CURRENT_VERSION, { name: 'X' }), context)
+    expect(res.status).toBe(200)
+    expect(mockEm.flush).toHaveBeenCalled()
+  })
+
+  it('PUT is a no-op (no 409) when the client sends no expected-version header', async () => {
+    const res = await PUT(request('PUT', null, { name: 'X' }), context)
+    expect(res.status).toBe(200)
+    expect(mockEm.flush).toHaveBeenCalled()
+  })
+
+  it('DELETE returns 409 when the expected version is stale', async () => {
+    const res = await DELETE(request('DELETE', STALE_VERSION), context)
+    expect(res.status).toBe(409)
+    const body = await res.json()
+    expect(body.code).toBe('optimistic_lock_conflict')
+    expect(mockEm.flush).not.toHaveBeenCalled()
+  })
+})

package/src/modules/webhooks/api/webhooks/[id]/route.ts

@@ -4,6 +4,8 @@ import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { emitWebhooksEvent } from '../../../events'
 import { findScopedWebhook, json, resolveWebhookRequestScope, serializeWebhookDetail } from '../../helpers'
 import { webhookUpdateSchema } from '../../../data/validators'
+import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 
 export const metadata = {
   GET: { requireAuth: true, requireFeatures: ['webhooks.view'] },
@@ -69,6 +71,18 @@ export async function PUT(request: Request, context: RouteContext): Promise<Resp
     return json({ error: 'Webhook not found' }, { status: 404 })
   }
 
+  try {
+    enforceCommandOptimisticLock({
+      resourceKind: 'webhooks.endpoint',
+      resourceId: webhook.id,
+      current: webhook.updatedAt ?? null,
+      request,
+    })
+  } catch (err) {
+    if (isCrudHttpError(err)) return json(err.body, { status: err.status })
+    throw err
+  }
+
   const parsed = webhookUpdateSchema.safeParse(await request.json().catch(() => null))
   if (!parsed.success) {
     return json({ error: 'Invalid request payload' }, { status: 400 })
@@ -114,6 +128,18 @@ export async function DELETE(request: Request, context: RouteContext): Promise<R
     return json({ error: translate('webhooks.errors.notFound', 'Webhook not found') }, { status: 404 })
   }
 
+  try {
+    enforceCommandOptimisticLock({
+      resourceKind: 'webhooks.endpoint',
+      resourceId: webhook.id,
+      current: webhook.updatedAt ?? null,
+      request,
+    })
+  } catch (err) {
+    if (isCrudHttpError(err)) return json(err.body, { status: err.status })
+    throw err
+  }
+
   webhook.deletedAt = new Date()
   await em.flush()