A Webhook Health Check Must Test the Event, Not Just the URL

A URL returning an error is not always proof that the workflow behind it is broken.

In a real OpenClaw operations check, a signed webhook delivery reached its handler and returned the expected accepted response. But an ordinary browser-style GET request to the same address fell through to a different upstream route and returned an error. Looking only at the GET result would have created a false outage report.

The request method is part of the service contract

Webhooks are event endpoints, not general web pages. Their contract usually includes a specific HTTP method, a signed payload, and an expected response code. A health check that ignores those requirements is testing a different path from the one the provider actually uses.

Monitor the real interaction, not a convenient approximation of it.

What changed in the monitoring approach

  • Identify the expected method, payload shape, signature requirement, and successful status code.
  • Keep unsigned or malformed requests as negative tests, not as health signals.
  • Use a dedicated health endpoint when a safe synthetic event cannot be produced.
  • Record delivery evidence separately from any unrelated browser or upstream-route failure.
  • Alert on the condition that would prevent real events from being processed.

Why this matters for automation

False alarms cost attention and can lead teams to change a healthy integration. A precise check gives the opposite benefit: it exposes the failure that matters, such as rejected signatures, an unavailable handler, or an unexpected response to the provider’s actual event.

The broader lesson applies to every integration. Before calling a workflow healthy or broken, test the contract it was built to satisfy. Accurate monitoring is not just observation; it is an operational safeguard.

Scroll to Top