fix(webhooks): CRC guidance gives conflicting validation schedules #501

Summary

The v2 Webhooks introduction describes hourly CRC validation and, on the same page, a conditional 30-minute schedule. The quickstart also promises hourly validation. These statements leave integrations without a consistent documented schedule for health checks; this report does not establish the actual service cadence.

Runtime or environment

Documentation source: current main commit 5fcfe3da51461ef1c0b59a028da9c365547cad4c. The repository has no published releases. The cited live Markdown pages were freshly fetched and compared with this checkout. No live X API calls were made.

Steps to reproduce

1. Read the security and webhook-validation sections of https://docs.x.com/x-api/webhooks/introduction.
2. Compare the automatic CRC schedules with the validation section of https://docs.x.com/x-api/webhooks/quickstart.
3. Observe that these sections describe the same v2 webhook infrastructure and /2/webhooks management routes, with no product or version distinction explaining the schedules.

These documentation comparisons were executed; no webhook was registered and no delivery interval was measured.

Expected behavior

The introduction and quickstart should consistently describe when automatic CRC requests are sent, including any different rules for routine validation and retries.

Actual behavior

The introduction security section says CRC checks occur hourly. Its webhook-validation section instead says they occur every 30 minutes only if no successful validation occurred in the past 24 hours. The quickstart states that automatic validation occurs every hour. A retry-versus-routine distinction might explain different intervals, but the text does not state one.

Evidence

• Expected source: x-api/webhooks/introduction.mdx, lines 84–90 and x-api/webhooks/quickstart.mdx, lines 41–44 describe hourly checks.
• Failure source: x-api/webhooks/introduction.mdx, lines 119–124 gives the conditional 30-minute schedule. Fresh .md versions of both linked live pages retain these statements.
• Evidence provenance: observed
• Local verification: reproduced
• Reproduction completeness: complete

Restoration check

Compare the same source and published sections after clarification. The schedules and conditions should agree, or explicitly distinguish separate mechanisms. Choosing one interval without establishing the service contract would not prove restoration.

Triage assessment

• Impact level: P2
• Assessment status: provisional
• Impact basis: The conflicting schedules can mislead webhook health monitoring and operational expectations. No actual monitoring or delivery failure was observed, so consequential impact is provisional.
• Workaround status: unverified
• Workaround basis: Responding to every incoming CRC avoids interval assumptions in receiver handling but does not resolve the affected cadence-based monitoring contract. No practical workaround for establishing that monitoring schedule was verified.