docs: add webhooks documentation (API only) [OD-702]

[claudiacodacy]

Summary

• Adds a new page documenting the M1 webhooks feature for its first release, API only: adding, listing, and deleting an organization webhook endpoint via the Codacy API (createWebhookEndpoint, listWebhookEndpoints, deleteWebhookEndpoint), the quality.analysis.completed event, the delivery payload and headers, HMAC-SHA256 signature verification, and delivery behavior (10s timeout, retry on 5xx/timeout, no retry on 4xx, dedupe on X-Codacy-Delivery for retries and commitSha for reanalysis).
• Registers the page under Organizations > Managing integrations in mkdocs.yml, alongside the Slack and Jira integration pages.
• Adds a row to the organization permissions table for adding/managing webhook endpoints.

This is a split of #2758. The org Integrations > Webhooks UI page (add-endpoint flow, signing-secret card, upgrade prompt) isn't built yet (OD-697, OD-699, OD-701, OD-709 are open) — we're shipping API access this week so Liberty Mutual and other requesters can try it, ahead of the UI. #2758 now carries the UI-specific delta on top of this page, and stays open to merge once the UI ships.

Sourcing

• Grounded in the current (2026-09-28) "Event webhooks" Linear project spec (OD-44) — US1–US8 and the wire event example, which already reflects the wire-contract changes called out in review on docs: add webhooks documentation (UI and API) [OD-702] #2758 (ISO 8601 timestamp in the signed body, no X-Codacy-Timestamp header, status field, retry behavior).
• The three API operations are cross-checked against the merged codacy-website apiv3.yaml (ace8d3b2a0, a0dedc9cbf — the real outbound-hooks backend proxy merged this morning, 2026-09-28) and WebhookServicesImpl.scala, which confirmed: only createWebhookEndpoint is gated by the organization's webhooks entitlement (403 ForbiddenAction if disabled), and all three operations require organization write permission (admin/manager).
• roles-and-permissions-for-organizations.md: added as footnote <sup>6</sup> — <sup>5</sup> was taken by #2763, merged after docs: add webhooks documentation (UI and API) [OD-702] #2758 was opened.

Test plan

• mkdocs build --strict passes with no warnings
• vale docs/organizations/integrations/webhooks.md docs/organizations/roles-and-permissions-for-organizations.md — clean except the pre-existing repo-wide em dash spacing style (Microsoft.Dashes), advisory, matches convention used throughout the rest of the docs
• nav: entry confirmed by eye in mkdocs.yml, and by build output (site/organizations/integrations/webhooks/index.html exists)

🤖 Generated with Claude Code

[github-actions]

Overall readability score: 54.21 (🟢 +0.05)

File	Readability
roles-and-permissions-for-organizations.md	61.87 (🟢 +0.35)
webhooks.md	68.53 (-)

View detailed metrics

🟢 - Shows an increase in readability
🔴 - Shows a decrease in readability

File	Readability	FRE	GF	ARI	CLI	DCRS
roles-and-permissions-for-organizations.md	61.87	31.17	8.45	11.9	12.93	6.21
	🟢 +0.35	🟢 +0.1	🟢 +0.07	🟢 +0.1	🟢 +0.05	🟢 +0
webhooks.md	68.53	47.59	8.72	10	10.55	6.74
	-	-	-	-	-	-

Averages:

	Readability	FRE	GF	ARI	CLI	DCRS
Average	54.21	43.01	10.9	12.33	12.27	7.99
	🟢 +0.05	🟢 +0.02	🟢 +0.01	🟢 +0.01	🟢 +0.01	🟢 +0

View metric targets

Metric	Range	Ideal score
Flesch Reading Ease	100 (very easy read) to 0 (extremely difficult read)	60
Gunning Fog	6 (very easy read) to 17 (extremely difficult read)	8 or less
Auto. Read. Index	6 (very easy read) to 14 (extremely difficult read)	8 or less
Coleman Liau Index	6 (very easy read) to 17 (extremely difficult read)	8 or less
Dale-Chall Readability	4.9 (very easy read) to 9.9 (extremely difficult read)	6.9 or less

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

AI Reviewer: first review requested successfully. AI can make mistakes. Always validate suggestions.

_{TIP This summary will be updated as you push new changes.}

[codacy-production]

Pull Request Overview

No merge-blocking implementation issues were identified. Codacy reports the PR is up to standards, with no new issues or coverage findings.

The acceptance criteria lack automated verification, particularly for strict MkDocs/Vale validation, navigation, permissions, API examples, payload handling, and delivery behavior.

About this PR

• Add automated documentation validation covering strict MkDocs/Vale checks, navigation, permissions, API operations, payload/signature details, and delivery behavior.

Test suggestions

• Validate the webhook documentation builds with mkdocs build --strict and is included in the generated site.
• Validate the webhook page is registered under Organizations > Managing integrations.
• Validate documentation covers create, list, and delete API operations with permissions and entitlement behavior.
• Validate documentation describes event triggers and payload variants for branch and pull request analyses.
• Validate documentation describes all delivery headers and HMAC-SHA256 verification steps.
• Validate documentation describes timeout, retry, 4xx behavior, and delivery deduplication rules.
• Validate the organization permissions table grants webhook endpoint management to organization managers and admins only.

Prompt proposal for missing tests

Consider implementing these tests if applicable:
1. Validate the webhook documentation builds with mkdocs build --strict and is included in the generated site.
2. Validate the webhook page is registered under Organizations > Managing integrations.
3. Validate documentation covers create, list, and delete API operations with permissions and entitlement behavior.
4. Validate documentation describes event triggers and payload variants for branch and pull request analyses.
5. Validate documentation describes all delivery headers and HMAC-SHA256 verification steps.
6. Validate documentation describes timeout, retry, 4xx behavior, and delivery deduplication rules.
7. Validate the organization permissions table grants webhook endpoint management to organization managers and admins only.

_{TIP Improve review quality by adding custom instructions
TIP How was this review? Give us feedback}

[claudiacodacy]

Closing as superseded by #2758. Since the front end is almost ready, we only need one docs PR. #2758 is retargeted to master and contains everything from this PR (page, nav entry, permissions row, wire-contract fixes and retry timing), plus the UI walkthrough.