Designing API Webhook Subscription Limits: How Many Endpoints Per Customer Is the Right Number

An API with webhooks lets customers register HTTP endpoints to receive events. The first version of every webhook product allows one endpoint per customer. The second version allows several—because customers want different events going to different systems, or test endpoints separate from production, or fan-out to multiple downstream services. The question that the second version forces is: how many endpoints should one customer be allowed to register?

The answer is not "as many as they want." A pure no-limit policy creates a category of abuse where a single customer with thousands of endpoints multiplies your delivery infrastructure load by thousands. It also creates support burden when customers register endpoints they then forget about, which fail silently, which accumulate as dead webhook subscriptions for years. The right limit balances support cost against legitimate integration patterns, and the right number is much smaller than most teams initially guess.

What customers actually use endpoints for

The first design input is observing what customers actually do with multiple endpoints. The patterns cluster into a small set:

Production-vs-test separation: one endpoint for production traffic, one for staging or development. This is the most common multi-endpoint pattern and covers maybe 60-70% of customers who use more than one endpoint.

Event-type routing: different event categories going to different internal systems. Invoice events go to billing; user events go to CRM; system events go to monitoring. Mature integrations typically have 3-5 endpoints serving this pattern.

Geographic or regional routing: customers with global infrastructure registering endpoints in each region for latency or data-residency reasons. This is rarer but produces high endpoint counts when it happens—a customer with five regions and three event categories needs 15 endpoints.

Fan-out to multiple downstream services: less common than it sounds because most customers do fan-out themselves rather than have the provider do it.

The implication of looking at actual usage is that the limit needs to comfortably accommodate the geographic-routing case, which is the high end of legitimate multi-endpoint usage. 20-50 endpoints covers nearly all cases. Limits below 10 cut off real customers; limits above 100 enable abuse without serving real use cases.

What the limit accomplishes

The limit serves three purposes the customer does not see and one they do.

Cost protection: every endpoint a customer registers requires delivery infrastructure, signature secret storage, retry state, and audit logs. The marginal cost per endpoint is small but nonzero, and accumulating thousands of dead endpoints from sloppy customers eventually adds up.

Abuse prevention: a malicious or compromised customer could register thousands of endpoints pointing at attack-target servers, turning your webhook delivery into a DDoS amplifier. The limit caps this attack vector.

Operational quality: investigating a webhook problem for a customer with three endpoints is straightforward. Investigating for a customer with 500 endpoints requires substantial filtering and pattern matching just to find the relevant deliveries. Operational difficulty grows nonlinearly in endpoint count.

The customer-visible purpose is forcing them to think about endpoint hygiene. A 25-endpoint limit makes customers organize their integration consciously; an unlimited-endpoint policy lets them register and forget, accumulating cruft.

Common limit shapes

Surveying public webhook providers as of late 2025: Stripe defaults to 16 webhook endpoints per account, with higher limits available on request. GitHub allows 20 webhook endpoints per repository plus organization-level webhooks. Shopify allows 50 per app per shop. Twilio allows 100 per account. Linear allows 10 per workspace by default. The convergence is striking—nearly everyone lands in the 10-100 range, with most around 25-50.

The clustering reflects the actual usage patterns. Customers who need more than 50 endpoints almost always have unusual architecture (multi-region geographic routing, or many sub-tenants masquerading as one customer), and the higher limits are typically negotiated rather than offered by default.

Per-account vs. per-resource limits

The second design decision is whether the limit applies at the account level or at finer granularity. GitHub's per-repository limit is finer than per-account; Stripe's per-account limit is coarser; Shopify's per-app-per-shop combines both.

The right granularity depends on the product's resource model. If customers have multiple billing accounts or environments or workspaces that they manage somewhat independently, per-resource limits feel natural. If the account is the primary organizational unit, per-account limits are simpler.

The implementation cost is identical—both are just rows in a counting table. The customer-experience cost diverges: per-resource limits force customers to think about resource organization, which is sometimes useful and sometimes annoying.

The deactivation question

An underused safety valve is auto-deactivating endpoints that fail consistently. An endpoint that fails 100% of deliveries for a week is almost certainly broken on the customer's side—the receiving server is gone, the URL is wrong, or the integration was abandoned. Auto-deactivation reclaims the endpoint slot from the customer's limit and stops wasted delivery attempts.

The right pattern is conservative: auto-deactivate after some threshold (Stripe uses persistent 4xx failures over multiple days), notify the customer via dashboard banner and email, and require explicit reactivation. The customer who actually wants the endpoint can reactivate; the customer who has forgotten about it never does, and the dead endpoint stops counting against their limit.

This pattern reduces effective endpoint pressure substantially. A 25-endpoint limit with aggressive auto-deactivation handles more legitimate use than a 100-endpoint limit without it, because the slots are not occupied by long-dead integrations.

Three patterns that fail

Limits below 10: customers hit the limit during normal integration setup, especially the production-vs-test-vs-staging case. Support tickets are common; customer frustration is high.

Unlimited endpoints: abuse vector remains open, support burden accumulates over years, operational tooling has to handle pathological cases that probably should not exist. The lack of a forcing function for endpoint hygiene shows up downstream.

Identical limit for all customer tiers: free-tier customers and enterprise customers have very different endpoint needs. The tier-based limit pattern (free: 3, paid: 25, enterprise: negotiated) matches both the cost asymmetry and the actual usage asymmetry.

Across our four products

Our four products take different approaches because the webhook product fit varies.

WebhookVault has the most webhook-centric model—the entire product is webhook endpoint management. We allow 10 endpoints on the free tier, 50 on starter, 200 on pro, 1000 on business. The high upper end matches the typical WebhookVault customer pattern of using endpoints as debugging surfaces, where many temporary endpoints get created and discarded.

CronPing sends webhook notifications for monitor state changes. We allow 5 webhook endpoints on free, 25 on starter, 100 on pro, 500 on business—matching the typical pattern of "one endpoint per integration target" with a few production-vs-test variants.

FlagBit sends webhook notifications for flag changes. We allow 3 webhook endpoints on free, 10 on starter, 50 on pro, 200 on business. The lower numbers reflect the typical FlagBit integration pattern of one endpoint per environment (dev/staging/prod) plus a few overflow slots.

DocuMint uses webhooks only for Stripe billing events incoming, not for outbound notifications. There is no customer-facing webhook subscription limit because DocuMint does not yet support outbound webhooks.

The auto-deactivation infrastructure is shared across the three products that support outbound webhooks, with deactivation after 14 consecutive days of 100% failure rates, customer-facing dashboard surface showing deactivated endpoints, and one-click reactivation.

The deeper observation about webhook subscription limits is that the right number is much smaller than most providers initially imagine and much larger than most customers initially imagine. The convergence around 25-50 reflects accumulated observation across many webhook products, and the unusual approach is usually a sign that someone has not done the homework of looking at what comparable products do and why.

Our products: DocuMint (PDF invoice generation API), CronPing (cron job monitoring with status pages), FlagBit (feature flags API for modern teams), and WebhookVault (webhook capture and replay) put these patterns into production.