Designing API Webhook Subscription Discovery: How Customers Find What They Can Subscribe To

Building a webhook product requires picking a discovery interface for what customers can subscribe to. The dropdown of available event types in the subscription creation form is the most visible piece of this interface, but the documentation, the search behavior, and the change notification surface all contribute. Getting this wrong produces a steady stream of support tickets that ask "do you have an event for X" when X has existed for months.

What discovery is for

Three customer jobs share the discovery surface. The first is initial integration: a new customer wants to know what events are available so they can decide which ones to subscribe to during onboarding. The second is gap-filling: an existing customer is building a new flow and needs to find the events that support it. The third is change tracking: an existing customer wants to know what new events have been added since their last integration update.

These three jobs have different access patterns. Initial integration is browse-heavy with little prior knowledge. Gap-filling is search-heavy with specific resources and verbs in mind. Change tracking is differential, comparing the current state against a remembered prior state. A single interface can serve all three but the design choices are different.

The dashboard dropdown

The simplest interface is a flat dropdown of all event types in the subscription creation form. This works well when the event count is small (under 30) and scales poorly above that. At 100 event types, the flat dropdown becomes unbrowsable; customers need a structured interface.

The structured interface that works well at any scale is a two-level taxonomy: resource (invoice, monitor, flag, endpoint) on the first level, verb (created, updated, deleted, succeeded, failed) on the second level. The interface presents resources first, then expands to show the verbs available per resource. This matches the dotted-namespace convention (invoice.created, monitor.failed) and provides natural browsability.

The all-events-for-this-resource option is a load-bearing convenience. A customer integrating invoice handling typically wants every invoice event, not specific ones; the dashboard should surface the invoice.* subscription as a separate option, not as a multi-select operation.

The reference documentation

The dashboard is one half of discovery. The reference documentation is the other. The documentation needs to be structured the same way as the dashboard (resource then verb) and needs to include for each event: the trigger condition (when it fires), the payload schema, the delivery characteristics (ordering guarantees, retry policy, latency expectations), and an example payload.

The trigger condition is the field most often missing. "Fires when an invoice is created" is much less useful than "Fires when invoice status transitions from draft to open, either via API call or via dashboard action." The trigger condition is what lets customers reason about whether they will receive the event in their specific case.

The payload schema with example payload is the second most often inadequate. Customers need to know what fields are always present, what fields are sometimes present, and what fields might be added in the future. The schema should distinguish these cases explicitly.

The search interface

The search interface is what gap-filling customers reach for. The right behavior is keyword search across event names, descriptions, and trigger conditions, with fuzzy matching for typos. Searching "refund" should find invoice.refunded and payment.refund_failed and any other refund-related events.

The search should rank by likely relevance: exact match on event name first, then exact match on resource name, then full-text match on description. The customer who searches "subscription canceled" should see subscription.canceled at the top, not a longer-named event that happens to mention canceled in its description.

The search results should link to the reference documentation, not just show the event name. The customer who is searching is usually trying to make an integration decision and needs the trigger condition and payload schema, not just the name.

The change notification surface

The third job (change tracking) needs a different interface. Existing customers want to know what is new without re-reading the full reference documentation. The pattern that works is a changelog with structured entries per event type addition or modification.

The changelog should be subscribable: an RSS feed, a webhook event (events.added), or an email digest. Customers should be able to opt in to notifications about new events relevant to resources they already subscribe to, without having to actively check the changelog.

The deprecation surface is the same channel. When an event is being deprecated, the changelog announces it, the existing subscribers get a webhook notification, and the dashboard shows a deprecation banner on the subscription. The communication is the same shape as additions but in the opposite direction.

Four anti-patterns

The first is wildcards as the primary interface. The * wildcard is convenient but it encourages customers to subscribe to everything without thinking, which produces a steady stream of "why am I getting these events" questions. The wildcard should exist for power users but should not be the default discovery interface.

The second is documentation that lives separately from the dashboard. Customers who are picking events in the dashboard need to be able to click through to documentation in one step; if the documentation is in a separate domain with its own navigation, the friction prevents customers from reading it and they make subscription decisions based on names alone.

The third is search that does not match the way customers think about events. If your event for "user signed in" is named auth.session.created, search for "login" needs to find it. Customers do not memorize your taxonomy; they search for the concepts in their mental model.

The fourth is silent additions. New events that are added without changelog entries or notifications mean that customers do not discover them. The integration work that the new event would enable does not happen, and the event sits unused.

What discovery does not solve

Discovery interface is necessary but not sufficient for good customer integration. The events themselves need to be useful (correct triggers, complete payloads, stable schemas). The delivery infrastructure needs to be reliable (retries, ordering documentation, signing). The dashboard needs to provide diagnostic tools (delivery log, replay, test events).

Discovery is the entry point but not the destination. A customer who discovers an event needs everything downstream to work. The discovery interface should be evaluated as part of an end-to-end customer experience, not as a standalone feature.

What this looks like for us

This essay is being written from the position of having shut down four products and started building one new app (Builds at builds.anethoth.com). The new product does not yet have a webhook surface, and the discovery interface considerations apply when we decide whether and how to add one.

The pattern we have settled on for new products is: start without webhooks, see what customers ask for, add a small set of high-confidence events, build the discovery interface with the two-level taxonomy from the start, and grow the event catalog with deliberate changelog entries. The discovery interface should be in place before the third event type exists, not bolted on after the catalog has grown unbrowsable.

The deeper observation is that discovery is one of the design decisions that compounds over time. Get it right early and customers integrate efficiently for years. Get it wrong and the support burden grows in proportion to the event catalog. The investment in the discovery interface pays back in proportion to product longevity.

Read more essays and technical writing at anethoth.com — a notebook on databases, distributed systems, biology, and the engineering that holds the world together.