/v4/webhook_endpoints). For the general API error model, see response codes.
422 Unprocessable — validation
Returned when the request body is invalid. Common cases:
eventsis empty — an endpoint must subscribe to at least one event type.urlis missing or not a public HTTP(S) URL.descriptionis too long.
403 Forbidden — app-managed endpoints
Endpoints created by an app (via OAuth) are owned by that app. An API key cannot update or delete an app-managed endpoint — that returns 403. (An app reaching for an endpoint it didn’t create is scoped out entirely and gets a 404, covered below.)
401 Unauthorized — plan access
If the account’s plan doesn’t include API/webhook access (for example a free plan or a lapsed trial), the endpoints return 401. See response codes for the full list of 401 causes.
404 Not found — access gating
The webhook endpoints return 404 (rather than revealing existence) when:
- Webhooks aren’t enabled for the account (the feature is off).
- The endpoint id belongs to another account, or to an app other than the caller.
Duplicate URLs are allowed
Pointing more than one endpoint at the same URL is not an error — for example, one endpoint per event set, or rotating an endpoint by standing up a replacement before removing the old one. If two endpoints on the same URL subscribe to overlapping events, that URL receives one delivery per endpoint carrying the same events (same eventids); deduplicate on the event id.