Bug 1658844 - Move Webhooks user guide to Sphinx documentation

[loganrosen]

Bugzilla currently serves the Webhooks user guide from a page.cgi template. That keeps the guide out of BMO's published documentation and leaves user-facing documentation tied to an application page.

This moves the guide into the Webhooks extension's Sphinx documentation, where the existing Installed Extensions toctree includes it automatically, and updates the Webhooks preferences tab to link to the generated Read the Docs page. The interactive webhook queue remains in page.cgi.

The migrated content was also checked against the current UI, serializer, connector, privacy checks, queue, and backoff implementation. The guide now reflects current event and filter permissions, authentication-header behavior, payload shapes, private/public transitions, HTTP 2xx success handling, retry timing, queue ordering, and automatic disabling after repeated errors.

Bug: https://bugzilla.mozilla.org/show_bug.cgi?id=1658844

Testing:

• Built the Sphinx HTML documentation with the pinned requirements.
• Parsed all four JSON payload examples and checked their event-specific shapes.

[Copilot]

Pull request overview

Migrates the Webhooks user guide into BMO’s Sphinx documentation and updates the preferences page to reference it.

Changes:

• Adds an updated Webhooks guide with payload and retry details.
• Links Webhook preferences to Read the Docs.
• Removes the legacy page.cgi guide.

Show a summary per file

File	Description
docs/en/rst/extensions/Webhooks/index-user.rst	Adds the Sphinx user guide.
extensions/Webhooks/template/en/default/account/prefs/webhooks.html.tmpl	Updates the documentation link.
extensions/Webhooks/template/en/default/pages/webhooks.html.tmpl	Removes the legacy guide.

Review details

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

• Files reviewed: 3/3 changed files
• Comments generated: 2
• Review effort level: Balanced

[Copilot]

Review details

Suppressed comments (2)

Previously missed (2) — in code that hasn't changed since the last review.

docs/en/rst/extensions/Webhooks/index-user.rst:352

• The exact 5/25/125/625-second sequence is not restarted after recovery. The connector backoff is reset only when Push::start runs (extensions/Push/lib/Push.pm:31-39); successful backlog delivery removes the message without resetting it (Push.pm:182-185). A later failure during the same daemon run can therefore jump directly to a longer delay, including 15 minutes. Either reset the backoff when a backlog drains or document that the connector-wide backoff persists.

failed queued attempt, it schedules the next attempt using increasing delays:
5 seconds after the first failure, then 25, 125, and 625 seconds. After later
failures, the delay is 15 minutes. The delivery daemon polls every 30 seconds,
so an attempt can occur later than its scheduled time.

docs/en/rst/extensions/Webhooks/index-user.rst:360

• The limit applies to an individual queued message's attempt count (extensions/Push/lib/BacklogMessage.pm:110-117), not a cumulative error count on the webhook, and enforcement is skipped for the configured error-exempt group (extensions/Webhooks/Extension.pm:364-369). The current wording presents both the scope and disabling behavior as unconditional.

An administrator can configure an error limit. When a webhook reaches that
limit, Bugzilla disables it and emails its owner. The owner can re-enable it
from the :guilabel:`Webhooks` preferences tab after fixing the problem.

• Files reviewed: 3/3 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

Review details

Suppressed comments (2)

Previously missed (2) — in code that hasn't changed since the last review.

docs/en/rst/extensions/Webhooks/index-user.rst:101

• The connector explicitly deletes event.changes when the target is private, and a public-to-private transition intentionally reports only the synthetic is_private change. Therefore, saying it contains every change overpromises the payload contract; scope this statement to ordinary public modifications and document the omission for private payloads.

modification events each produce a separate request. The ``changes`` field is
sent only for modification events and contains every change made to the event
target, such as the bug or attachment.

docs/en/rst/extensions/Webhooks/index-user.rst:42

• The event selections are not independent in the current connector: a stored attachment_change value also matches both /change/ and /attachment/ in Connector/Webhook.pm, so selecting only attachment modifications additionally delivers bug modifications and attachment creations. Either make the connector token-match the comma-separated event values or explicitly document the extra events; as written, this list promises filtering the implementation does not provide.

      * When an existing attachment is modified.

• Files reviewed: 3/3 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[dklawren]

LGTM r=dkl