Register the full webhook URL including the path, and make the handler route match it exactly. Providers POST to the exact string you registered - they do not guess the path - so a registration missing the trailing path lands on a route that does not exist and every event 404s. Copy the URL from the running service's route table rather than typing it from memory.

```text
agent registered the webhook URL without the trailing path  -  the provider delivered to the wrong route and events 404d
```

## Steps

1. Open the provider dashboard and read the exact webhook URL registered there, character for character.
   Expected: You have the registered URL written down exactly as the provider sees it.

2. Check the actual route in the service: the framework's route table, the server config, or the handler's path annotation. Compare it against the registered URL.
   Expected: You can state whether the registered URL and the real route match, and how they differ.

3. Update the registration to the exact full path. If the route itself was wrong, fix the service route first, redeploy, then update the registration to match.
   Expected: The registered URL and the service route are identical strings.

4. Send a test event from the provider dashboard and confirm the handler returns 200, not 404. Check the provider's delivery log for the successful attempt.
   Expected: Test deliveries return 200 from the webhook handler and the delivery log shows success.

## Use this when

- the provider's delivery log shows 404s for webhook events
- the registered URL differs from the service's actual route
- the agent registered the domain root or a partial path

## Not for this skill when

- deliveries fail signature verification - that is a signing problem, not a routing problem
- the handler returns 500 - the route is right but the handler code has a bug
- events arrive but are not processed - look at the handler logic, not the URL

## Variant phrasings

### webhook 404 not found
### webhook URL path mismatch
### events delivered to wrong route
### webhook registration missing path

## Why it happens

The agent registered the base URL and assumed routing would figure out the rest - a reasonable assumption from apps where one domain serves one purpose. But a webhook registration is a literal string the provider replays verbatim on every event. There is no path guessing, no redirect following you can rely on, so a missing path segment means the request hits the framework's 404 handler instead of your code.

## Edge cases

- Trailing slashes matter on some frameworks: /hooks and /hooks/ can be different routes
- Staging and production URLs get mixed up - verify which environment's URL is registered
- The URL must be publicly reachable: a private host or VPN-only address 404s or times out from the provider's side
- After any redeploy that changes routes, re-verify the registration still matches

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_MrA0oF2ex3sdTQ95OnNvOw