@open-mercato/webhooks 0.10.1-develop.7618.1.ba9531c18e → 0.10.1-develop.7622.1.0584ba2a04

package/src/modules/webhooks/api/webhooks/[id]/__tests__/credential-headers.test.ts

@@ -0,0 +1,358 @@
+/** @jest-environment node */
+
+const WEBHOOK_ID = '123e4567-e89b-12d3-a456-426614174237'
+const REDACTED = '••••••••'
+
+type StoredWebhook = Record<string, unknown> & { customHeaders: Record<string, string> | null }
+
+function makeWebhook(): StoredWebhook {
+  return {
+    id: WEBHOOK_ID,
+    name: 'Hook',
+    description: null,
+    url: 'https://example.com/hook',
+    secret: 'whsec_abcdefghijklmnop',
+    subscribedEvents: ['catalog.product.created'],
+    httpMethod: 'POST',
+    isActive: true,
+    deliveryStrategy: 'http',
+    maxRetries: 3,
+    consecutiveFailures: 0,
+    lastSuccessAt: null,
+    lastFailureAt: null,
+    createdAt: new Date('2026-06-01T10:00:00.000Z'),
+    updatedAt: new Date('2026-06-01T10:00:00.000Z'),
+    customHeaders: {
+      Authorization: 'Bearer live-destination-token',
+      'x-api-key': 'dest-api-key-123',
+      'x-mock-webhook-token': 'shared-secret',
+      'x-source': 'open-mercato',
+    },
+    strategyConfig: null,
+    timeoutMs: 5000,
+    rateLimitPerMinute: 0,
+    autoDisableThreshold: 5,
+    integrationId: null,
+    previousSecretSetAt: null,
+    organizationId: 'org-1',
+    tenantId: 'tenant-1',
+    deletedAt: null,
+  }
+}
+
+let webhookRecord = makeWebhook()
+let grantedFeatures: string[] = []
+
+const mockRbac = {
+  userHasAllFeatures: jest.fn(async (_sub: string, required: string[]) =>
+    required.every((feature) => grantedFeatures.includes(feature) || grantedFeatures.includes('webhooks.*')),
+  ),
+  loadAcl: jest.fn(async () => ({ isSuperAdmin: false, features: grantedFeatures, organizations: null })),
+}
+
+const mockEm = {
+  fork: jest.fn(() => mockEm),
+  flush: jest.fn(async () => undefined),
+}
+
+const mockContainer = {
+  resolve: (token: string) => {
+    if (token === 'em') return mockEm
+    if (token === 'rbacService') return mockRbac
+    if (token === 'cache') return null
+    if (token === 'commandOptimisticLockGuardService') throw new Error('not registered')
+    return null
+  },
+}
+
+const authContext = { sub: 'user-1', tenantId: 'tenant-1', orgId: 'org-1', roles: [] }
+
+jest.mock('../../../../events', () => ({
+  emitWebhooksEvent: jest.fn(async () => undefined),
+}))
+
+jest.mock('../../../../lib/subscription-cache', () => ({
+  invalidateWebhookSubscriptionCacheFor: jest.fn(async () => undefined),
+}))
+
+jest.mock('../../../helpers', () => {
+  const actual = jest.requireActual('../../../helpers')
+  return {
+    ...actual,
+    resolveWebhookRequestScope: jest.fn(async () => ({
+      container: mockContainer,
+      em: mockEm,
+      tenantId: 'tenant-1',
+      organizationId: 'org-1',
+      allowedOrganizationIds: null,
+      auth: authContext,
+    })),
+    findScopedWebhook: jest.fn(async () => webhookRecord),
+  }
+})
+
+jest.mock('@open-mercato/shared/lib/i18n/server', () => ({
+  resolveTranslations: jest.fn(async () => ({
+    translate: (_key: string, fallback?: string, params?: Record<string, string>) =>
+      (fallback ?? '').replace(/\{(\w+)\}/g, (_match, name: string) => params?.[name] ?? ''),
+  })),
+}))
+
+import { GET, PUT } from '../route'
+
+const context = { params: Promise.resolve({ id: WEBHOOK_ID }) }
+
+function request(method: string, body?: unknown) {
+  return new Request(`http://localhost/api/webhooks/${WEBHOOK_ID}`, {
+    method,
+    headers: { 'content-type': 'application/json' },
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  })
+}
+
+async function readHeaders(res: Response): Promise<Record<string, string> | null> {
+  const body = (await res.json()) as { customHeaders: Record<string, string> | null }
+  return body.customHeaders
+}
+
+describe('webhook custom credential headers (issue #7237)', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+    webhookRecord = makeWebhook()
+  })
+
+  describe('GET', () => {
+    it('redacts credential-like header values for a webhooks.view-only caller', async () => {
+      grantedFeatures = ['webhooks.view']
+
+      const headers = await readHeaders(await GET(request('GET'), context))
+
+      expect(headers).toEqual({
+        Authorization: REDACTED,
+        'x-api-key': REDACTED,
+        'x-mock-webhook-token': REDACTED,
+        'x-source': 'open-mercato',
+      })
+    })
+
+    it('keeps the response shape: header names stay visible, values stay strings', async () => {
+      grantedFeatures = ['webhooks.view']
+
+      const headers = await readHeaders(await GET(request('GET'), context))
+
+      expect(Object.keys(headers ?? {}).sort()).toEqual(
+        ['Authorization', 'x-api-key', 'x-mock-webhook-token', 'x-source'].sort(),
+      )
+      for (const value of Object.values(headers ?? {})) expect(typeof value).toBe('string')
+    })
+
+    it('redacts for webhooks.manage without webhooks.secrets', async () => {
+      grantedFeatures = ['webhooks.view', 'webhooks.manage']
+
+      const headers = await readHeaders(await GET(request('GET'), context))
+
+      expect(headers?.Authorization).toBe(REDACTED)
+    })
+
+    it('returns values verbatim to a webhooks.secrets holder', async () => {
+      grantedFeatures = ['webhooks.view', 'webhooks.secrets']
+
+      const headers = await readHeaders(await GET(request('GET'), context))
+
+      expect(headers).toEqual(makeWebhook().customHeaders)
+    })
+
+    it('checks webhooks.secrets in the scope of the webhook being returned', async () => {
+      grantedFeatures = ['webhooks.view']
+
+      await GET(request('GET'), context)
+
+      expect(mockRbac.userHasAllFeatures).toHaveBeenCalledWith('user-1', ['webhooks.secrets'], {
+        tenantId: 'tenant-1',
+        organizationId: 'org-1',
+      })
+    })
+
+    it('returns null headers unchanged', async () => {
+      grantedFeatures = ['webhooks.view']
+      webhookRecord.customHeaders = null
+
+      expect(await readHeaders(await GET(request('GET'), context))).toBeNull()
+    })
+  })
+
+  describe('PUT', () => {
+    beforeEach(() => {
+      grantedFeatures = ['webhooks.view', 'webhooks.manage']
+    })
+
+    it('keeps stored credential values when the redaction marker is echoed back', async () => {
+      const res = await PUT(
+        request('PUT', {
+          name: 'Renamed',
+          customHeaders: {
+            Authorization: REDACTED,
+            'x-api-key': REDACTED,
+            'x-mock-webhook-token': REDACTED,
+            'x-source': 'erp',
+          },
+        }),
+        context,
+      )
+
+      expect(res.status).toBe(200)
+      expect(webhookRecord.customHeaders).toEqual({
+        Authorization: 'Bearer live-destination-token',
+        'x-api-key': 'dest-api-key-123',
+        'x-mock-webhook-token': 'shared-secret',
+        'x-source': 'erp',
+      })
+      expect(webhookRecord.name).toBe('Renamed')
+    })
+
+    it('matches the stored header case-insensitively when the marker is echoed', async () => {
+      await PUT(request('PUT', { customHeaders: { authorization: REDACTED } }), context)
+
+      expect(webhookRecord.customHeaders).toEqual({ authorization: 'Bearer live-destination-token' })
+    })
+
+    it('replaces a credential value when a new one is sent', async () => {
+      await PUT(request('PUT', { customHeaders: { Authorization: 'Bearer rotated' } }), context)
+
+      expect(webhookRecord.customHeaders).toEqual({ Authorization: 'Bearer rotated' })
+    })
+
+    it('drops a credential header the caller omits', async () => {
+      await PUT(request('PUT', { customHeaders: { 'x-source': 'erp' } }), context)
+
+      expect(webhookRecord.customHeaders).toEqual({ 'x-source': 'erp' })
+    })
+
+    it('rejects the marker for a header that has no stored value instead of saving it', async () => {
+      const res = await PUT(request('PUT', { customHeaders: { 'x-new-token': REDACTED } }), context)
+
+      expect(res.status).toBe(400)
+      expect(webhookRecord.customHeaders).toEqual(makeWebhook().customHeaders)
+    })
+
+    it('redacts the PUT response the same way as GET for a caller without webhooks.secrets', async () => {
+      const res = await PUT(request('PUT', { name: 'Renamed' }), context)
+
+      expect((await readHeaders(res))?.Authorization).toBe(REDACTED)
+    })
+    it('names the header in the orphan-marker error', async () => {
+      const res = await PUT(request('PUT', { customHeaders: { 'x-new-token': REDACTED } }), context)
+
+      expect(((await res.json()) as { error: string }).error).toContain('x-new-token')
+    })
+
+    it('stores a value that only starts with the marker as a new value', async () => {
+      await PUT(request('PUT', { customHeaders: { Authorization: `${REDACTED}x` } }), context)
+
+      expect(webhookRecord.customHeaders).toEqual({ Authorization: `${REDACTED}x` })
+    })
+
+    it('clears all headers when customHeaders is null', async () => {
+      await PUT(request('PUT', { customHeaders: null }), context)
+
+      expect(webhookRecord.customHeaders).toBeNull()
+    })
+
+    it('rejects an ambiguous marker when two stored names differ only by case', async () => {
+      webhookRecord.customHeaders = { Authorization: 'Bearer a', authorization: 'Bearer b' }
+
+      const res = await PUT(request('PUT', { customHeaders: { AUTHORIZATION: REDACTED } }), context)
+
+      expect(res.status).toBe(400)
+      expect(webhookRecord.customHeaders).toEqual({ Authorization: 'Bearer a', authorization: 'Bearer b' })
+    })
+
+    it('matches a stored name that differs only by surrounding whitespace', async () => {
+      webhookRecord.customHeaders = { ' Authorization': 'Bearer padded' }
+
+      await PUT(request('PUT', { customHeaders: { Authorization: REDACTED } }), context)
+
+      expect(webhookRecord.customHeaders).toEqual({ Authorization: 'Bearer padded' })
+    })
+  })
+
+  describe('PUT with a changed URL', () => {
+    it('refuses to keep hidden credential values for a caller without webhooks.secrets', async () => {
+      grantedFeatures = ['webhooks.view', 'webhooks.manage']
+
+      const res = await PUT(
+        request('PUT', {
+          url: 'https://attacker.example.net/collect',
+          customHeaders: { Authorization: REDACTED, 'x-source': 'open-mercato' },
+        }),
+        context,
+      )
+
+      expect(res.status).toBe(400)
+      expect(((await res.json()) as { error: string }).error).toContain('Authorization')
+      expect(webhookRecord.url).toBe('https://example.com/hook')
+      expect(webhookRecord.customHeaders).toEqual(makeWebhook().customHeaders)
+    })
+
+    it('refuses when customHeaders is omitted and stored credential headers would follow the new URL', async () => {
+      grantedFeatures = ['webhooks.view', 'webhooks.manage']
+
+      const res = await PUT(request('PUT', { url: 'https://attacker.example.net/collect' }), context)
+
+      expect(res.status).toBe(400)
+      expect(webhookRecord.url).toBe('https://example.com/hook')
+    })
+
+    it('accepts the move when the caller re-enters or removes every credential header', async () => {
+      grantedFeatures = ['webhooks.view', 'webhooks.manage']
+
+      const res = await PUT(
+        request('PUT', {
+          url: 'https://other.example.net/hook',
+          customHeaders: { Authorization: 'Bearer re-entered', 'x-source': 'open-mercato' },
+        }),
+        context,
+      )
+
+      expect(res.status).toBe(200)
+      expect(webhookRecord.url).toBe('https://other.example.net/hook')
+      expect(webhookRecord.customHeaders).toEqual({ Authorization: 'Bearer re-entered', 'x-source': 'open-mercato' })
+    })
+
+    it('refuses when only the path changes on the same host', async () => {
+      grantedFeatures = ['webhooks.view', 'webhooks.manage']
+
+      const res = await PUT(
+        request('PUT', { url: 'https://example.com/attacker-bin', customHeaders: { Authorization: REDACTED } }),
+        context,
+      )
+
+      expect(res.status).toBe(400)
+      expect(webhookRecord.url).toBe('https://example.com/hook')
+    })
+
+    it('keeps hidden values when the unchanged URL is sent back', async () => {
+      grantedFeatures = ['webhooks.view', 'webhooks.manage']
+
+      const res = await PUT(
+        request('PUT', { name: 'Renamed', url: 'https://example.com/hook', customHeaders: { Authorization: REDACTED } }),
+        context,
+      )
+
+      expect(res.status).toBe(200)
+      expect(webhookRecord.customHeaders).toEqual({ Authorization: 'Bearer live-destination-token' })
+    })
+
+    it('lets a webhooks.secrets holder keep stored values on a new host', async () => {
+      grantedFeatures = ['webhooks.view', 'webhooks.manage', 'webhooks.secrets']
+
+      const res = await PUT(
+        request('PUT', { url: 'https://other.example.net/hook', customHeaders: { Authorization: REDACTED } }),
+        context,
+      )
+
+      expect(res.status).toBe(200)
+      expect(webhookRecord.customHeaders).toEqual({ Authorization: 'Bearer live-destination-token' })
+    })
+  })
+})

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

@@ -56,6 +56,8 @@ jest.mock('../../../helpers', () => ({
     }),
   resolveWebhookRequestScope: jest.fn(async () => ({ container: mockContainer, em: mockEm, tenantId: 'tenant-1', organizationId: 'org-1' })),
   findScopedWebhook: jest.fn(async () => (webhookRecord.deletedAt ? null : webhookRecord)),
+  canRevealWebhookCredentialHeaders: jest.fn(async () => true),
+  translateWebhookCustomHeadersRejection: jest.fn(async () => 'rejected'),
   serializeWebhookDetail: (item: { id: string; updatedAt: Date }) => ({
     id: item.id,
     updatedAt: item.updatedAt.toISOString(),

package/src/modules/webhooks/api/webhooks/[id]/__tests__/reactivation.test.ts

@@ -46,6 +46,8 @@ jest.mock('../../../helpers', () => ({
     organizationId: 'org-1',
   })),
   findScopedWebhook: jest.fn(async () => webhookRecord),
+  canRevealWebhookCredentialHeaders: jest.fn(async () => true),
+  translateWebhookCustomHeadersRejection: jest.fn(async () => 'rejected'),
   serializeWebhookDetail: (item: { id: string; isActive: boolean; consecutiveFailures: number }) => ({
     id: item.id,
     isActive: item.isActive,

package/src/modules/webhooks/api/webhooks/[id]/__tests__/subscription-cache-invalidation.test.ts

@@ -55,6 +55,8 @@ jest.mock('../../../helpers', () => ({
     organizationId: 'org-1',
   })),
   findScopedWebhook: jest.fn(async () => webhookRecord),
+  canRevealWebhookCredentialHeaders: jest.fn(async () => true),
+  translateWebhookCustomHeadersRejection: jest.fn(async () => 'rejected'),
   serializeWebhookDetail: (item: { id: string }) => ({ id: item.id }),
 }))
 

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

@@ -2,12 +2,20 @@ import { z } from 'zod'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { emitWebhooksEvent } from '../../../events'
-import { findScopedWebhook, json, resolveWebhookRequestScope, serializeWebhookDetail } from '../../helpers'
+import {
+  canRevealWebhookCredentialHeaders,
+  findScopedWebhook,
+  json,
+  resolveWebhookRequestScope,
+  serializeWebhookDetail,
+  translateWebhookCustomHeadersRejection,
+} from '../../helpers'
 import { webhookUpdateSchema } from '../../../data/validators'
 import { enforceCommandOptimisticLockWithGuards } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { invalidateWebhookSubscriptionCacheFor } from '../../../lib/subscription-cache'
 import { applyWebhookActiveState } from '../../../lib/activation'
+import { planWebhookCustomHeadersUpdate } from '../../../lib/custom-headers'
 
 export const metadata = {
   GET: { requireAuth: true, requireFeatures: ['webhooks.view'] },
@@ -34,7 +42,9 @@ const webhookDetailResponseSchema = z.object({
   lastFailureAt: z.string().nullable(),
   createdAt: z.string(),
   updatedAt: z.string(),
-  customHeaders: z.record(z.string(), z.string()).nullable(),
+  customHeaders: z.record(z.string(), z.string()).nullable().describe(
+    'Credential-like header values are returned as •••••••• unless the caller has webhooks.secrets. Sending •••••••• back on update keeps the stored value.',
+  ),
   strategyConfig: z.record(z.string(), z.unknown()).nullable(),
   timeoutMs: z.number(),
   rateLimitPerMinute: z.number(),
@@ -58,7 +68,8 @@ export async function GET(request: Request, context: RouteContext): Promise<Resp
     return json({ error: 'Webhook not found' }, { status: 404 })
   }
 
-  return json(serializeWebhookDetail(webhook))
+  const revealCredentialHeaders = await canRevealWebhookCredentialHeaders(scope.container, scope.auth, webhook)
+  return json(serializeWebhookDetail(webhook, { revealCredentialHeaders }))
 }
 
 export async function PUT(request: Request, context: RouteContext): Promise<Response> {
@@ -91,12 +102,22 @@ export async function PUT(request: Request, context: RouteContext): Promise<Resp
   }
 
   const input = parsed.data
+  const revealCredentialHeaders = await canRevealWebhookCredentialHeaders(scope.container, scope.auth, webhook)
+  const headersUpdate = planWebhookCustomHeadersUpdate({
+    current: webhook,
+    next: input,
+    canRevealCredentials: revealCredentialHeaders,
+  })
+  if (!headersUpdate.ok) {
+    return json({ error: await translateWebhookCustomHeadersRejection(headersUpdate) }, { status: 400 })
+  }
+
   if (input.name !== undefined) webhook.name = input.name
   if (input.description !== undefined) webhook.description = input.description
   if (input.url !== undefined) webhook.url = input.url
   if (input.subscribedEvents !== undefined) webhook.subscribedEvents = input.subscribedEvents
   if (input.httpMethod !== undefined) webhook.httpMethod = input.httpMethod
-  if (input.customHeaders !== undefined) webhook.customHeaders = input.customHeaders
+  if (headersUpdate.customHeaders !== undefined) webhook.customHeaders = headersUpdate.customHeaders
   if (input.deliveryStrategy !== undefined) webhook.deliveryStrategy = input.deliveryStrategy
   if (input.strategyConfig !== undefined) webhook.strategyConfig = input.strategyConfig
   if (input.maxRetries !== undefined) webhook.maxRetries = input.maxRetries
@@ -116,7 +137,7 @@ export async function PUT(request: Request, context: RouteContext): Promise<Resp
     tenantId: webhook.tenantId,
   }, { persistent: true })
 
-  return json(serializeWebhookDetail(webhook))
+  return json(serializeWebhookDetail(webhook, { revealCredentialHeaders }))
 }
 
 export async function DELETE(request: Request, context: RouteContext): Promise<Response> {
@@ -183,7 +204,11 @@ export const openApi: OpenApiRouteDoc = {
       },
       responses: [{ status: 200, description: 'Webhook updated', schema: webhookDetailResponseSchema }],
       errors: [
-        { status: 400, description: 'Invalid payload', schema: errorSchema },
+        {
+          status: 400,
+          description: 'Invalid payload, a hidden header value with no stored value, or a URL change that keeps hidden header values for a caller without webhooks.secrets',
+          schema: errorSchema,
+        },
         { status: 401, description: 'Unauthorized', schema: errorSchema },
         { status: 404, description: 'Webhook not found', schema: errorSchema },
       ],

package/src/modules/webhooks/api/webhooks/__tests__/credential-headers.test.ts

@@ -0,0 +1,96 @@
+/** @jest-environment node */
+
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+
+type ApplyToEntity = (entity: Record<string, unknown>, input: Record<string, unknown>, ctx: unknown) => Promise<void> | void
+
+const captured: { applyToEntity: ApplyToEntity | null } = { applyToEntity: null }
+
+jest.mock('@open-mercato/shared/lib/crud/factory', () => ({
+  makeCrudRoute: jest.fn((options: { update?: { applyToEntity?: ApplyToEntity } }) => {
+    captured.applyToEntity = options.update?.applyToEntity ?? null
+    return { metadata: {}, GET: jest.fn(), POST: jest.fn(), PUT: jest.fn(), DELETE: jest.fn() }
+  }),
+}))
+
+jest.mock('@open-mercato/shared/lib/i18n/server', () => ({
+  resolveTranslations: jest.fn(async () => ({ translate: (_key: string, fallback?: string) => fallback ?? '' })),
+}))
+
+import '../route'
+
+const REDACTED = '••••••••'
+
+let grantedFeatures: string[] = []
+const userHasAllFeatures = jest.fn(async (_sub: string, required: string[]) =>
+  required.every((feature) => grantedFeatures.includes(feature)),
+)
+const ctx = {
+  auth: { sub: 'user-1', tenantId: 'tenant-1', orgId: 'org-1' },
+  container: { resolve: (token: string) => (token === 'rbacService' ? { userHasAllFeatures } : null) },
+}
+
+function makeEntity() {
+  return {
+    id: 'webhook-1',
+    name: 'Hook',
+    url: 'https://example.com/hook',
+    tenantId: 'tenant-1',
+    organizationId: 'org-1',
+    customHeaders: { Authorization: 'Bearer stored', 'x-source': 'qa' } as Record<string, string> | null,
+  }
+}
+
+async function applyExpectingError(entity: Record<string, unknown>, input: Record<string, unknown>) {
+  try {
+    await captured.applyToEntity?.(entity, input, ctx)
+  } catch (error) {
+    return error
+  }
+  throw new Error('[internal] expected applyToEntity to throw')
+}
+
+describe('PUT /api/webhooks credential header handling (issue #7237)', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+    grantedFeatures = ['webhooks.view', 'webhooks.manage']
+  })
+
+  it('keeps the stored value when the redaction marker is echoed', async () => {
+    const entity = makeEntity()
+
+    await captured.applyToEntity?.(entity, { name: 'Renamed', customHeaders: { Authorization: REDACTED, 'x-source': 'erp' } }, ctx)
+
+    expect(entity.customHeaders).toEqual({ Authorization: 'Bearer stored', 'x-source': 'erp' })
+    expect(entity.name).toBe('Renamed')
+    expect(userHasAllFeatures).toHaveBeenCalledWith('user-1', ['webhooks.secrets'], { tenantId: 'tenant-1', organizationId: 'org-1' })
+  })
+
+  it('throws a 400 and changes nothing for a marker without a stored value', async () => {
+    const entity = makeEntity()
+
+    const error = await applyExpectingError(entity, { name: 'Renamed', customHeaders: { 'x-token': REDACTED } })
+
+    expect(isCrudHttpError(error) && error.status).toBe(400)
+    expect(entity).toEqual(makeEntity())
+  })
+
+  it('throws a 400 when stored credentials would follow a new host for a caller without webhooks.secrets', async () => {
+    const entity = makeEntity()
+
+    const error = await applyExpectingError(entity, { url: 'https://attacker.example.net/collect' })
+
+    expect(isCrudHttpError(error) && error.status).toBe(400)
+    expect(entity).toEqual(makeEntity())
+  })
+
+  it('lets a webhooks.secrets holder move stored credentials to a new host', async () => {
+    grantedFeatures = ['webhooks.view', 'webhooks.manage', 'webhooks.secrets']
+    const entity = makeEntity()
+
+    await captured.applyToEntity?.(entity, { url: 'https://other.example.net/hook' }, ctx)
+
+    expect(entity.url).toBe('https://other.example.net/hook')
+    expect(entity.customHeaders).toEqual(makeEntity().customHeaders)
+  })
+})

package/src/modules/webhooks/api/webhooks/route.ts

@@ -12,6 +12,9 @@ import { parseBooleanToken } from '@open-mercato/shared/lib/boolean'
 import type { WebhookCreateInput, WebhookUpdateInput } from '../../data/validators'
 import { invalidateWebhookSubscriptionCacheFor } from '../../lib/subscription-cache'
 import { applyWebhookActiveState } from '../../lib/activation'
+import { planWebhookCustomHeadersUpdate } from '../../lib/custom-headers'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { canRevealWebhookCredentialHeaders, translateWebhookCustomHeadersRejection } from '../helpers'
 
 type WebhookCrudCtx = CrudCtx & {
   __webhookSecret?: string
@@ -59,7 +62,9 @@ const webhookCreateResponseSchema = z.object({
 })
 
 const webhookDetailResponseSchema = webhookListItemSchema.extend({
-  customHeaders: z.record(z.string(), z.string()).nullable(),
+  customHeaders: z.record(z.string(), z.string()).nullable().describe(
+    'Credential-like header values are returned as •••••••• unless the caller has webhooks.secrets. Sending •••••••• back on update keeps the stored value.',
+  ),
   strategyConfig: z.record(z.string(), z.unknown()).nullable(),
   timeoutMs: z.number(),
   rateLimitPerMinute: z.number(),
@@ -122,13 +127,21 @@ const crud = makeCrudRoute<WebhookCreateInput, WebhookUpdateInput, z.infer<typeo
   },
   update: {
     schema: webhookUpdateSchema,
-    applyToEntity: (entity, input) => {
+    applyToEntity: async (entity: WebhookEntity, input, ctx) => {
+      const headersUpdate = planWebhookCustomHeadersUpdate({
+        current: entity,
+        next: input,
+        canRevealCredentials: await canRevealWebhookCredentialHeaders(ctx.container, ctx.auth, entity),
+      })
+      if (!headersUpdate.ok) {
+        throw new CrudHttpError(400, { error: await translateWebhookCustomHeadersRejection(headersUpdate) })
+      }
       if (input.name !== undefined) entity.name = input.name
       if (input.description !== undefined) entity.description = input.description
       if (input.url !== undefined) entity.url = input.url
       if (input.subscribedEvents !== undefined) entity.subscribedEvents = input.subscribedEvents
       if (input.httpMethod !== undefined) entity.httpMethod = input.httpMethod
-      if (input.customHeaders !== undefined) entity.customHeaders = input.customHeaders
+      if (headersUpdate.customHeaders !== undefined) entity.customHeaders = headersUpdate.customHeaders
       if (input.deliveryStrategy !== undefined) entity.deliveryStrategy = input.deliveryStrategy
       if (input.strategyConfig !== undefined) entity.strategyConfig = input.strategyConfig
       if (input.maxRetries !== undefined) entity.maxRetries = input.maxRetries
@@ -291,7 +304,11 @@ export const openApi: OpenApiRouteDoc = {
       requestBody: { contentType: 'application/json', schema: webhookUpdateSchema, description: 'Fields to update.' },
       responses: [{ status: 200, description: 'Webhook updated', schema: webhookDetailResponseSchema }],
       errors: [
-        { status: 400, description: 'Invalid payload', schema: errorSchema },
+        {
+          status: 400,
+          description: 'Invalid payload, a hidden header value with no stored value, or a URL change that keeps hidden header values for a caller without webhooks.secrets',
+          schema: errorSchema,
+        },
         { status: 404, description: 'Not found', schema: errorSchema },
       ],
     },

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

@@ -45,9 +45,11 @@
   "webhooks.detail.testResult": "Latest Test Result",
   "webhooks.detail.testSuccess": "Test delivery succeeded.",
   "webhooks.detail.title": "Webhook Detail",
+  "webhooks.errors.credentialHeadersRequireReentry": "Der Header \"{header}\" hat einen verborgenen Wert. Geben Sie ihn erneut ein oder entfernen Sie ihn, wenn Sie die Webhook-URL ändern.",
   "webhooks.errors.forbidden": "You do not have permission to perform this action.",
   "webhooks.errors.notFound": "Webhook not found.",
   "webhooks.errors.orgRequired": "Organization context required.",
+  "webhooks.errors.redactedHeaderWithoutValue": "Der Header \"{header}\" hat einen verborgenen Wert, aber keinen gespeicherten Wert, der beibehalten werden kann. Geben Sie den Header-Wert ein.",
   "webhooks.errors.tenantRequired": "Tenant context required.",
   "webhooks.form.advancedStrategyTip": "HTTP delivery is active today. Use custom headers for routing hints, and keep secrets out of request headers.",
   "webhooks.form.autoDisableThreshold": "Auto-Disable Threshold",
@@ -55,7 +57,7 @@
   "webhooks.form.createError": "Failed to create webhook.",
   "webhooks.form.createSuccess": "Webhook created successfully.",
   "webhooks.form.customHeaders": "Custom Headers",
-  "webhooks.form.customHeadersHint": "Optional JSON object of additional headers to send with each webhook request.",
+  "webhooks.form.customHeadersHint": "Optionales JSON-Objekt mit zusätzlichen Headern, die mit jeder Webhook-Anfrage gesendet werden. Verborgene Werte (••••••••) bleiben beim Speichern erhalten; ersetzen Sie einen Wert, um ihn zu ändern.",
   "webhooks.form.customHeadersInvalid": "Custom headers must be a valid JSON object with string values.",
   "webhooks.form.customHeadersTip": "Use headers for static metadata such as environment or source identifiers. Do not put access tokens or secrets here.",
   "webhooks.form.deliveryDefaultsTip": "The defaults are a safe starting point for most consumers. Increase retries or timeout only if the receiver is known to be slow.",

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

@@ -45,9 +45,11 @@
   "webhooks.detail.testResult": "Latest Test Result",
   "webhooks.detail.testSuccess": "Test delivery succeeded.",
   "webhooks.detail.title": "Webhook Detail",
+  "webhooks.errors.credentialHeadersRequireReentry": "Header \"{header}\" has a hidden value. Enter it again or remove it when you change the webhook URL.",
   "webhooks.errors.forbidden": "You do not have permission to perform this action.",
   "webhooks.errors.notFound": "Webhook not found.",
   "webhooks.errors.orgRequired": "Organization context required.",
+  "webhooks.errors.redactedHeaderWithoutValue": "Header \"{header}\" has a hidden value but no saved value to keep. Enter the header value.",
   "webhooks.errors.tenantRequired": "Tenant context required.",
   "webhooks.form.advancedStrategyTip": "HTTP delivery is active today. Use custom headers for routing hints, and keep secrets out of request headers.",
   "webhooks.form.autoDisableThreshold": "Auto-Disable Threshold",
@@ -55,7 +57,7 @@
   "webhooks.form.createError": "Failed to create webhook.",
   "webhooks.form.createSuccess": "Webhook created successfully.",
   "webhooks.form.customHeaders": "Custom Headers",
-  "webhooks.form.customHeadersHint": "Optional JSON object of additional headers to send with each webhook request.",
+  "webhooks.form.customHeadersHint": "Optional JSON object of additional headers to send with each webhook request. Hidden values (••••••••) are kept when you save; replace one to change it.",
   "webhooks.form.customHeadersInvalid": "Custom headers must be a valid JSON object with string values.",
   "webhooks.form.customHeadersTip": "Use headers for static metadata such as environment or source identifiers. Do not put access tokens or secrets here.",
   "webhooks.form.deliveryDefaultsTip": "The defaults are a safe starting point for most consumers. Increase retries or timeout only if the receiver is known to be slow.",