## TL;DR

The agent registered handlers for event names from the docs' wishlist, but the provider never emits those types. Real events went to unhandled types. List the provider's actual event catalog, subscribe to the ones that exist, and log unhandled types so gaps are visible.

## Error

```text
webhook handler received zero events for a week while the dashboard showed activity
```

## Steps

1. Pull the provider's real event type catalog (API or dashboard) Expected: you have the true list.
2. Diff it against the subscribed types Expected: you see the phantom subscriptions.
3. Subscribe to the real types and map them to handlers Expected: events start arriving.
4. Log and alert on unhandled event types Expected: future catalog drift is visible.

## When to use

- Webhook handlers never fire
- The agent invented event names from aspirational docs

## When not to use

- Events arrive but fail verification (different bug)
- The provider genuinely emits those types (then check the subscription)

## Tool compatibility

- Provider event catalogs
- Webhook handlers

## Variant phrasings

### webhooks never arrive

The event types you subscribed to may not exist. Diff against the real catalog.

### idle webhook handler

Same: subscribe to event types the provider actually emits.

## Why it happens

Docs sometimes document planned events alongside live ones. Agents cannot tell which is which and subscribe to everything.

## Edge cases

- Event names can differ between docs and payloads (e.g. dots vs underscores); compare against real payloads
- Some providers require enabling event types per endpoint, not just subscribing

## Provenance

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