Skip to main content
These are the errors you may encounter on the webhook management endpoints (/v4/webhook_endpoints). For the general API error model, see response codes.

​
422 Unprocessable — validation

Returned when the request body is invalid. Common cases:
  • events is empty — an endpoint must subscribe to at least one event type.
  • url is missing or not a public HTTP(S) URL.
  • description is too long.
  • On delivery history, a status or event_type filter that isn’t a recognized value, or an include_payload other than true or false.

​
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.
  • A delivery id doesn’t belong to the endpoint, or is older than the 30-day retention window.

​
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 event ids); deduplicate on the event id.