@@ -11,14 +11,14 @@
 {% if commonParams.size > 0 %}
 ## Common payload parameters
 
-Most webhook events include these standard parameters:
+Many webhook events include these parameters. Not every event includes each one, and whether a parameter is required varies by event.
 
 | Name | Type | Description |
 |------|------|-------------|
 {% for param in commonParams %}| `{{ param.name }}` | `{{ param.type }}` | {% if param.isRequired %}**Required.** {% endif %}{{ param.description }} |
 {% endfor %}
 
-Events below list only their additional parameters beyond these common ones.
+Events below omit these common parameters from their own tables.
 
 {% endif %}
 {% for webhook in webhooks %}
 
@@ -0,0 +1,109 @@
+import { beforeAll, describe, expect, test, vi } from 'vitest'
+
+import { WebhooksTransformer } from '@/article-api/transformers/webhooks-transformer'
+import { getWebhooks } from '@/webhooks/lib/index'
+import { allVersions } from '@/versions/lib/all-versions'
+import type { Context, Page } from '@/types'
+
+// Wrap the real loader so the real-data tests keep using synced data while one test injects a fixture.
+vi.mock('@/webhooks/lib/index', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@/webhooks/lib/index')>()
+  return { ...actual, getWebhooks: vi.fn(actual.getWebhooks) }
+})
+
+const stubPage = {
+  autogenerated: 'webhooks',
+  title: 'Webhook events and payloads',
+  intro: '',
+  renderProp: async () => '',
+} as unknown as Page
+
+function getCommonRow(body: string, name: string): string {
+  const commonSection = body.split('## Common payload parameters')[1]?.split('\n## ')[0] || ''
+  return commonSection.split('\n').find((line) => line.startsWith(`| \`${name}\` |`)) || ''
+}
+
+async function renderBody(currentVersion = 'free-pro-team@latest'): Promise<string> {
+  const context = {
+    currentVersion,
+    currentVersionObj: allVersions[currentVersion],
+    allVersions,
+  } as unknown as Context
+  return await new WebhooksTransformer().transform(
+    stubPage,
+    '/en/webhooks/webhook-events-and-payloads',
+    context,
+  )
+}
+
+function makeAction(params: Array<[string, boolean]>) {
+  return {
+    bodyParameters: params.map(([paramName, isRequired]) => ({
+      name: paramName,
+      type: 'object',
+      description: `The ${paramName}.`,
+      isRequired,
+    })),
+  }
+}
+
+describe('WebhooksTransformer common parameters', () => {
+  let body = ''
+
+  beforeAll(async () => {
+    body = await renderBody()
+  })
+
+  // Some events, such as push, have no action field, so the shared rows cannot be required for all events.
+  test('common parameters are not marked required when some events omit them', () => {
+    for (const name of ['action', 'repository', 'sender']) {
+      const row = getCommonRow(body, name)
+      expect(row).toBeTruthy()
+      expect(row).not.toContain('**Required.**')
+    }
+  })
+
+  test('common section says required status varies by event', () => {
+    expect(body).toContain('whether a parameter is required varies by event')
+  })
+})
+
+describe('WebhooksTransformer common parameters with fixture data', () => {
+  test('marks a common row required only when every event requires it', async () => {
+    vi.mocked(getWebhooks).mockResolvedValueOnce({
+      first: {
+        default: makeAction([
+          ['action', true],
+          ['repository', true],
+          ['sender', true],
+        ]),
+      },
+      second: {
+        opened: makeAction([
+          ['action', true],
+          ['repository', true],
+          ['sender', true],
+        ]),
+        closed: makeAction([
+          ['action', true],
+          ['repository', false],
+          ['sender', true],
+        ]),
+      },
+      third: {
+        default: makeAction([
+          ['repository', true],
+          ['sender', true],
+        ]),
+      },
+    } as unknown as Awaited<ReturnType<typeof getWebhooks>>)
+    // Prepared webhooks are cached per version, so use a version the real-data tests do not load.
+    const fixtureBody = await renderBody('enterprise-cloud@latest')
+
+    expect(getCommonRow(fixtureBody, 'sender')).toContain('**Required.**')
+    expect(getCommonRow(fixtureBody, 'repository')).toBeTruthy()
+    expect(getCommonRow(fixtureBody, 'repository')).not.toContain('**Required.**')
+    expect(getCommonRow(fixtureBody, 'action')).toBeTruthy()
+    expect(getCommonRow(fixtureBody, 'action')).not.toContain('**Required.**')
+  })
+})
@@ -119,7 +119,7 @@ describe('Webhooks transformer', () => {
     expect(res.statusCode).toBe(200)
 
     expect(res.body).toContain('## Common payload parameters')
-    expect(res.body).toContain('Most webhook events include these standard parameters')
+    expect(res.body).toContain('Many webhook events include these parameters')
 
     const commonSection = res.body.split('## Common payload parameters')[1]?.split('\n## ')[0] || ''
     expect(commonSection).toContain('`sender`')
 
@@ -75,10 +75,19 @@ async function prepareWebhooks(currentVersion: string) {
   )
 
   // Omit high-frequency body parameters from rows; summarize matches from the first webhook.
-  const commonParams =
+  const commonParams = (
     preparedWebhooks[0]?.actions[0]?.bodyParameters.filter((p: { name: string }) =>
       commonParamNames.has(p.name),
     ) || []
+  ).map((param) => ({
+    ...param,
+    // The shared row replaces every event's own row, so it is required only if every event requires it.
+    isRequired: preparedWebhooks.every((webhook) =>
+      webhook.actions.every((action) =>
+        action.bodyParameters.some((p) => p.name === param.name && p.isRequired),
+      ),
+    ),
+  }))
   for (const webhook of preparedWebhooks) {
     for (const action of webhook.actions) {
       action.bodyParameters = action.bodyParameters.filter(