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

[claudiacodacy]

Single PR for webhooks docs. This was split in two (#2767 API only, #2758 UI walkthrough) so the API page could ship ahead of the UI. The org Integrations UI is now almost ready, so we only need this one PR. #2767 is closed as superseded, and this PR carries everything.

Summary

• Adds the org webhooks page, organizations/integrations/webhooks.md, registered under Organizations > Managing integrations next to the Slack and Jira integration pages.
• UI walkthrough: open Integrations, page Webhooks, add an endpoint by its Payload URL, copy the signing secret from the card (shown once), delete an endpoint, the 10-endpoint limit, and the upgrade prompt for organizations without access.
• API: the same operations through createWebhookEndpoint, listWebhookEndpoints and deleteWebhookEndpoint, with curl examples.
• Wire contract: the quality.analysis.completed event, payload and headers, HMAC-SHA256 verification, and delivery behavior (10 s timeout, 5xx and timeout retried up to 2 more times at about 1 s then 5 s, 4xx not retried, dedupe on X-Codacy-Delivery for retries and commitSha for reanalysis).
• Adds a row and footnote 6 to the organization permissions table.

No IA change: the page sits where both earlier PRs put it, and no file moves, so no redirects are needed.

Sourcing

• UI labels are read from the merged codacy-spa code (@d063ccddc: OD-696, OD-697, OD-698, OD-701, OD-709). The signing-secret card is from the still-open codacy-spa#3144 (OD-699).
• API operations and wire contract as reviewed on docs: add webhooks documentation (UI and API) [OD-702] #2758 and docs: add webhooks documentation (API only) [OD-702] #2767 (outbound-hooks#15 and Sync docs #24, codacy-events#260).

Before merging

• Merge after the org Integrations UI ships. codacy-spa#3144 (OD-699) is still open, and the UI is still behind the tempEventWebhooks flag.
• codacy-spa#3144 links "How to verify deliveries" to #delivery-payload. Verification is under #verifying-a-delivery, so the link should change there.
• The docs don't say whether non-admin members can see the endpoint list. The UI shows them a read-only list, but the list API needs organization write permission (per docs: add webhooks documentation (API only) [OD-702] #2767).

Test plan

• mkdocs build --strict passes with no warnings
• nav: entry present in mkdocs.yml, and site/organizations/integrations/webhooks/index.html is built
• vale on the two changed pages: only the existing em-dash spacing (Microsoft.Dashes) and "backoff" flags remain

🤖 Generated with Claude Code

[github-actions]

Overall readability score: 54.21 (🟢 +0.01)

File	Readability
roles-and-permissions-for-organizations.md	61.87 (🟢 +0)
webhooks.md	70.75 (🟢 +2.21)

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	🟢 +0	🟢 +0	🟢 +0	🟢 +0	🟢 +0
webhooks.md	70.75	47.89	8.25	9.8	10.43	6.46
	🟢 +2.21	🟢 +0.3	🟢 +0.47	🟢 +0.2	🟢 +0.12	🟢 +0.28

Averages:

	Readability	FRE	GF	ARI	CLI	DCRS
Average	54.21	43.01	10.9	12.33	12.27	7.99
	🟢 +0.01	🟢 +0	🟢 +0	🟢 +0	🟢 +0	🟢 +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

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

[andrzej-janczak]

In "Delivery behavior", please also note that Codacy retries a 5xx or a timeout up to 2 more times (200 ms, 400 ms delay) before giving up; only a 4xx drops immediately, without retry. A retry reuses the same X-Codacy-Delivery value, so integrators should dedupe on X-Codacy-Delivery for retries and on commitSha for reanalysis. Matches outbound-hooks#15.

[claudiacodacy]

Addressed both, on #2767 (the wire-contract content, inherited here):

• Wire contract: dropped `X-Codacy-Timestamp`, moved `timestamp` into the signed body as ISO 8601 (`2025-09-17T23:00:00Z`), added `status` (`success`/`partial_success`/`failure`).
• Delivery behavior: `5xx`/timeout retries up to 2 more times (200 ms, 400 ms), `4xx` drops immediately, retries reuse `X-Codacy-Delivery`.

Also split this PR in two: #2767 ships the API-only page this week (org Integrations UI isn't built yet), and this PR now carries just the UI walkthrough on top, to merge once the UI ships.

[andrzej-janczak]

Update to the retry timing (outbound-hooks#24): a 5xx or timeout is now retried with exponential backoff, about 1 s then 2 s (with jitter), still 3 attempts in total; a 4xx is not retried. Please use these numbers instead of 200 ms / 400 ms.

[andrzej-janczak]

Correction to my previous note: the retry delays are about 1 s then 5 s (exponential factor 5, with jitter), still 3 attempts in total; a 4xx is not retried.

[claudiacodacy]

Retargeted to master and now carries the full webhooks docs (UI walkthrough, API, wire contract). Since the front end is almost ready, we only need this one PR, so I've closed #2767 as superseded. The two changes since the last review: the UI walkthrough now sits alongside the API section (the curl examples are back), and the labels are checked against the merged codacy-spa code. Three open items are listed under "Before merging" in the description.