Which Read the Docs alerting setup keeps build-failure signal but drops PR build noise?

Question

We maintain a documentation project on Read the Docs (readthedocs.org) with pull request builds enabled, and the volume of build notifications has become a problem. Maintainers receive failure emails, and we also configured a project webhook that posts build events into a chat channel, but every PR and feature-branch build fires a delivery, so genuinely important failures on the default branch get buried.

My understanding is that the dashboard offers limited per-event control over email notifications, and that recipients are tied to project membership, while webhooks fire per build event with state and version fields in the payload. That suggests filtering has to happen downstream — in the chat integration or a small intermediary service — but I am unsure which combination is the intended, maintainable approach, and whether the community and commercial offerings differ here.

Assuming a current Read the Docs dashboard (settings may have changed over time):

Can email failure notifications be scoped to specific versions or branches, or is the only lever the maintainer list itself?
For webhook-based alerts, is filtering payloads by build state and version (e.g., failures on the default branch only) the documented way to cut noise, or is there a native event selection I am missing?
Does disabling PR builds remove their webhook deliveries entirely, or do they still fire with a distinguishable build type?

Tasadduq Burney · Answer

AnswerEmail failure notifications cannot be scoped to specific branches; the only lever is the maintainer list itself. To silence PR‑build noise while preserving alerts for genuine failures on the default branch, filter the webhook payload downstream (or manually filter email in your client). Disabling PR builds removes both email and webhook deliveries for those PRs entirely.Confirmed factsEmail alerts are sent to all project maintainers for any failed build; the dashboard offers no per‑branch or per‑version scoping.Webhook deliveries include a JSON payload with state (triggered, building, success, failed) and a version object containing slug (e.g., "main" or "pr/42").When PR builds are enabled, PR‑build webhooks are distinguishable by the version slug (typically prefixed with "pr/") or by a type indicator in the version object.Disabling PR builds under Settings → Builds → Pull Requests stops both email and webhook notifications for those PRs.Steps to keep default‑branch failure signals and drop PR noiseLeave PR builds enabled if you want contributors to see preview builds.Configure your webhook receiver to forward a message only when:payload.state === "failed"payload.version.slug === "" (or, equivalently, !payload.version.slug.startsWith("pr/"))Test the filter** by triggering a failed build on a feature branch (should produce no chat message) and a failed build on the default branch (should produce a message).Email handling**: Since email cannot be scoped, either accept all failure emails and filter them in your mail client, or set up a simple mail‑forwarding rule that forwards only messages whose subject/body indicates the default branch.Missing diagnostic detailTo complete the filter you need to know the exact slug of your default branch (e.g., "main", "master", "release"). If you provide that, the filter can be written definitively; otherwise you must inspect a sample webhook payload to determine it.

Which Read the Docs alerting setup keeps build-failure signal but drops PR build noise?

1 answer

Answer

Confirmed facts

Steps to keep default‑branch failure signals and drop PR noise

Missing diagnostic detail

Your perspective belongs here.

0 question comments