If events are not reaching your app
Most local delivery issues come from provider URL drift, an incomplete target URL, a local server that is not running, or webhook handler middleware. Walk through the checklist before digging deeper.
Delivery checklist
- The webhook provider uses the URL from tofu hooks url.
- Your local server is running before you set or test the target.
- The target URL includes the full local route path.
- Signed webhook handlers read the raw request body.
- Use delivery diagnosis on failed or non-2xx attempts before changing targets.
- Replay only works before payload expiry and before manual payload expiry.
What to try next
Keep tofu watch running while you trigger a provider test event. If Tofu receives the event but delivery fails, update the target URL, run delivery diagnosis from the event detail page, and replay the latest event before its payload expires.
tofu replay latest --hook stripeDelivery diagnosis
Failed and non-2xx deliveries can be diagnosed from the dashboard. Tofu first applies generic HTTP checks for timeouts, unreachable targets, route errors, payload limits, validation failures, and server exceptions. When a provider is recognized, Tofu adds provider-specific checks before returning evidence, a likely cause, suggested fixes, and verification steps.
Signature verification failing
If the provider returns 200 but your handler rejects the body with a signature error, make sure the handler reads the raw request bytes before parsing. Framework body parsers can mutate the payload and break Stripe's, GitHub's, or Clerk's HMAC checks.