docs: add webhooks documentation [OD-702]

[claudiacodacy]

Summary

• Adds a new page documenting organization Webhooks: adding and managing an endpoint from the org Integrations > Webhooks page, the quality.analysis.completed event (branch analysis finished / pull request analysis finished), the delivery payload and headers, HMAC-SHA256 signature verification, and delivery behavior (10s timeout, no retry, dedupe on commitSha).
• Registers the page under Organizations > Managing integrations in mkdocs.yml, alongside the Slack and Jira integration pages.

Sourcing

Grounded primarily in the current (2026-09-21) Linear project spec — US1–US8 and the wire event example — which is the authoritative description of what M1 ships, not the earlier repo-scoped design iterations it superseded. That means the page documents the full committed scope (add/list/delete an endpoint, both events, the signed payload, entitlement), not just the pieces already merged.

Cross-checked against the merged codacy-website apiv3.yaml webhook endpoints schemas and the shipped codacy-spa route/copy, but only to confirm naming and the page's URL — most of the UI this page documents (the add-endpoint flow, the signing-secret card, the upsell page) is still unbuilt (OD-697, OD-699, OD-701, OD-709 are open), and the merged v3 API is a mocked scaffold pending its real backend (OD-735).

Filed under organizations/integrations/ and named webhooks.md to match the docs path (organizations/integrations/webhooks/) already hardcoded in WebhooksPage.tsx.

Test plan

• mkdocs build --strict passes with no warnings
• vale docs/organizations/integrations/webhooks.md — clean except pre-existing repo-wide em dash spacing style (Microsoft.Dashes), which is advisory and matches convention used throughout the rest of the docs (e.g. organizations/managing-security-and-risk.md)
• nav: entry confirmed by eye in mkdocs.yml

🤖 Generated with Claude Code

[github-actions]

Overall readability score: 54.16 (🟢 +0.06)

File	Readability
roles-and-permissions-for-organizations.md	61.9 (🟢 +0.38)
webhooks.md	71.22 (-)

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.9	31.99	8.45	11.5	12.98	6.4
	🟢 +0.38	🟢 +0.1	🟢 +0.08	🟢 +0.1	🟢 +0.06	🟢 +0
webhooks.md	71.22	49.21	8.13	9.3	10.61	6.59
	-	-	-	-	-	-

Averages:

	Readability	FRE	GF	ARI	CLI	DCRS
Average	54.16	42.95	10.9	12.33	12.28	7.99
	🟢 +0.06	🟢 +0.02	🟢 +0.01	🟢 +0.01	🟢 +0.01	🟢 +0.01

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

The webhook verification documentation allows replay of captured valid deliveries because the timestamp and delivery ID are not covered by the signature and replay handling is not defined. This security gap should be addressed before merging.

The strict MkDocs build and several acceptance criteria remain unverified because no build artifact or automated test evidence is included. Codacy is up to standards; no uncovered complex files were reported.

Test suggestions

• Strict MkDocs build validates the new page and navigation entry without warnings.
• Documentation covers adding, deleting, endpoint limits, permissions, HTTPS validation, and signing-secret lifecycle.
• Documentation accurately describes branch and pull request event payloads and delivery conditions.
• Documentation accurately describes headers, HMAC-SHA256 verification, timeout, retry, and deduplication behavior.

Prompt proposal for missing tests

Consider implementing these tests if applicable:
1. Strict MkDocs build validates the new page and navigation entry without warnings.
2. Documentation covers adding, deleting, endpoint limits, permissions, HTTPS validation, and signing-secret lifecycle.
3. Documentation accurately describes branch and pull request event payloads and delivery conditions.
4. Documentation accurately describes headers, HMAC-SHA256 verification, timeout, retry, and deduplication behavior.

Low confidence findings

• Validate the documented endpoint-management flow against the shipped UI before relying on it as the authoritative guide.
• Add or link automated evidence that mkdocs build --strict completes without warnings.

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

[codacy-production]

_{🟡 MEDIUM RISK}

This verification flow permits replay of a captured, valid delivery. Include the timestamp and delivery ID in the signed material, or explicitly require consumers to deduplicate X-Codacy-Delivery values and document that the timestamp cannot be trusted for freshness unless it is covered by the signature. Define the exact HMAC input, require constant-time signature comparison, and explain rejection of duplicate delivery IDs and stale requests.

[andrzej-janczak]

Heads-up: the M1 wire contract changed after this was approved (outbound-hooks#15, codacy-events#260):

• X-Codacy-Timestamp header removed. The HMAC signs only the body, so an unsigned timestamp header could be replayed or altered without detection.
• Body timestamp is now an ISO 8601 UTC string, second precision (e.g. "2025-09-17T23:00:00Z"), not unix seconds. It is inside the signed body.
• New body field status: success, partial_success or failure. Webhooks now fire for failed analyses too.
  Please update the headers table, both JSON examples and the timestamp bullet before merging.

[claudiacodacy]

amazing