Article API: extract common webhook parameters and remove JSON examples (#60076)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: heiskr

src/article-api/templates/webhooks-page.template.md

@@ -8,6 +8,19 @@
 {{ manualContent }}
 {% endif %}
 
+{% if commonParams.size > 0 %}
+## Common payload parameters
+
+Most webhook events include these standard parameters:
+
+| 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.
+
+{% endif %}
 {% for webhook in webhooks %}
 ## {{ webhook.name }}
 
@@ -40,13 +53,5 @@
 {% for param in webhook.bodyParameters %}| `{{ param.name }}` | `{{ param.type }}` | {% if param.isRequired %}**Required.** {% endif %}{{ param.description }} |
 {% endfor %}
 
-{% endif %}
-{% if webhook.payloadExample %}
-### Webhook payload example
-
-```json
-{{ webhook.payloadExample }}
-```
-
 {% endif %}
 {% endfor %}

src/article-api/tests/webhooks-transformer.ts

@@ -122,11 +122,46 @@ describe('Webhooks transformer', () => {
     const res = await get(makeURL('/en/webhooks/webhook-events-and-payloads'))
     expect(res.statusCode).toBe(200)
 
-    // NOTE: The current webhook source data does not include payloadExample fields,
-    // so this section won't appear in the output. The transformer code (lines 115-120)
-    // is ready to display payload examples if/when they are added to the source data.
-    // For now, we just verify the transformer doesn't crash on missing examples.
+    // Payload examples are deliberately omitted from the article API output to save space.
+    // The property tables describe the payload structure instead.
+    expect(res.body).not.toContain('### Webhook payload example')
+    expect(res.body).not.toMatch(/```json/)
+  })
+
+  test('common parameters are extracted into a shared section', async () => {
+    const res = await get(makeURL('/en/webhooks/webhook-events-and-payloads'))
     expect(res.statusCode).toBe(200)
+
+    // Should have a common parameters section at the top
+    expect(res.body).toContain('## Common payload parameters')
+    expect(res.body).toContain('Most webhook events include these standard parameters')
+
+    // Common params like 'sender' and 'repository' should appear in the common section
+    // (they're in 60%+ of webhook events)
+    const commonSection = res.body.split('## Common payload parameters')[1]?.split('\n## ')[0] || ''
+    expect(commonSection).toContain('`sender`')
+    expect(commonSection).toContain('`repository`')
+  })
+
+  test('common parameters are not repeated in individual webhook sections', async () => {
+    const res = await get(makeURL('/en/webhooks/webhook-events-and-payloads'))
+    expect(res.statusCode).toBe(200)
+
+    // Find individual webhook sections after the common section
+    const sections = res.body.split('\n## ')
+    const webhookSections = sections.filter(
+      (s: string) => !s.startsWith('Common payload parameters') && !s.startsWith(sections[0]), // skip content before first ##
+    )
+
+    // In individual webhook parameter tables, common params should not appear
+    for (const section of webhookSections.slice(0, 3)) {
+      // If the section has a parameter table
+      if (section.includes('#### Webhook payload object parameters')) {
+        const tableContent = section.split('#### Webhook payload object parameters')[1] || ''
+        // 'sender' should NOT appear in individual tables
+        expect(tableContent).not.toMatch(/\|\s*`sender`\s*\|/)
+      }
+    }
   })
 
   test('Non-webhooks pages are not transformed', async () => {

src/article-api/transformers/webhooks-transformer.ts

@@ -48,7 +48,7 @@ export class WebhooksTransformer implements PageTransformer {
       }
     }
 
-    // Prepare webhooks data for template
+    // Prepare webhooks data for template (payload examples are omitted to save space)
     const preparedWebhooks = webhooksData.map((webhook) => ({
       name: webhook.name,
       actionTypes: webhook.actionTypes,
@@ -63,11 +63,31 @@ export class WebhooksTransformer implements PageTransformer {
           : '',
         isRequired: param.isRequired || false,
       })),
-      payloadExample: webhook.data.payloadExample
-        ? JSON.stringify(webhook.data.payloadExample, null, 2)
-        : null,
     }))
 
+    // Identify common body parameters that appear in most webhooks
+    const paramCounts = new Map<string, number>()
+    for (const webhook of preparedWebhooks) {
+      for (const param of webhook.bodyParameters) {
+        paramCounts.set(param.name, (paramCounts.get(param.name) || 0) + 1)
+      }
+    }
+    const threshold = preparedWebhooks.length * 0.6
+    const commonParamNames = new Set(
+      [...paramCounts.entries()].filter(([, count]) => count >= threshold).map(([name]) => name),
+    )
+
+    // Remove common params from each webhook and collect them for summary
+    const commonParams =
+      preparedWebhooks[0]?.bodyParameters.filter((p: { name: string }) =>
+        commonParamNames.has(p.name),
+      ) || []
+    for (const webhook of preparedWebhooks) {
+      webhook.bodyParameters = webhook.bodyParameters.filter(
+        (p: { name: string }) => !commonParamNames.has(p.name),
+      )
+    }
+
     // Prepare template data
     const templateData: Record<string, unknown> = {
       page: {
@@ -76,6 +96,7 @@ export class WebhooksTransformer implements PageTransformer {
       },
       manualContent,
       webhooks: preparedWebhooks,
+      commonParams,
     }
 
     // Load and render template