Read the Docs webhook notification filtering for high-frequency builds

Read the Docs does not provide native rate-limiting or consecutive-failure thresholds for webhook notifications. While the platform allows for basic filtering based on branch or tag glob patterns, it dispatches a payload for every build event that matches those criteria.

To handle high-frequency builds from rapid iteration cycles, you must move the filtering logic from the Read the Docs platform to your webhook consumer (the receiving endpoint).

Native Filtering Limitations

The only native suppression mechanism available within the Read the Docs UI is found under Project Settings > Integrations > Webhooks:

• Branch/Tag Filtering: You can use glob patterns (e.g., main, release/*) to prevent specific branches from triggering the webhook at all.
• Event Selection: You can toggle specific events (e.g., build:success, build:failure), but you cannot limit the frequency of these events.

Recommended Strategy: The Middleware Proxy

Since the platform cannot deduplicate or rate-limit, the standard architectural approach is to implement a lightweight middleware (such as an AWS Lambda, Google Cloud Function, or a simple microservice) between Read the Docs and your alerting tool (Slack, PagerDuty, etc.).

Your middleware should perform the following:

ol>

Branch Validation: Inspect the ref in the JSON payload. If it matches a noisy feature branch, discard the event.

State Tracking: Use a fast cache (like Redis) to track the count of consecutive failures per branch. Only forward the notification to your team when the count exceeds your threshold.

Rate Limiting: Implement a timestamp-based window to ignore subsequent builds for the same branch if they occur within a specific duration (e.g., 10 minutes).

Example Payload Inspection

When building your filter, you will primarily target these fields in the incoming Read the Docs payload:

{
  "event": "build:failure",
  "project": "my-project",
  "ref": "refs/heads/feature-rapid-iter",
  "status": "failed",
  "build_id": 12345
}

Are you currently using a specific CI/CD tool or a custom script to receive these webhooks? Knowing your stack could help provide a specific code snippet for the filtering logic.