Read the Docs and GitHub Webhook Integration: Build Failure Notification Granularity

Notification Granularity in Read the Docs

No, it is not currently possible to configure Read the Docs (RTD) to trigger build failure email notifications for specific tracked branches only. The notification settings are global to the project; if build failure notifications are enabled, an alert is sent regardless of whether the failure occurred on the stable version or a development branch.

Likely Cause of Notification Noise

Because RTD treats every tracked version as a first-class build target, any commit to a branch configured as a "version" triggers a full build process. When global notifications are active, the platform does not distinguish between a critical production regression and a transient error in a feature branch, leading to the "noise" experienced in multi-branch environments.

Recommended Approach for Isolation

To isolate critical stable-build alerts from development noise, you must shift the notification logic away from the RTD global settings and toward an external integration. The recommended workflow is as follows:

1. Disable Global Email Notifications: Turn off the project-wide build failure emails in the Read the Docs dashboard to stop the noise.
2. Implement a Webhook Listener: Use a middleware service (such as a custom GitHub Action, a Zapier flow, or a small serverless function) to listen for RTD build status webhooks.
3. Filter by Version: Configure the listener to inspect the payload of the webhook. RTD webhooks include the version name in the data.
4. Route Targeted Alerts: Program the listener to trigger a high-priority alert (e.g., Slack, PagerDuty, or a specific email address) only when the version field matches your stable/production branch.

Verification and Setup

To verify the data available for filtering, you can use a tool like Webhook.site to capture a live payload from Read the Docs. Ensure you are checking for the following key in the JSON response:

{ "version": "stable", "status": "failure", ... }

Diagnostic Detail Needed: Are you using the Read the Docs hosted platform (readthedocs.org) or a self-hosted instance? Self-hosted instances may allow for deeper configuration of the conf.py or server-side hooks that are unavailable on the hosted version.