Webhook Errors - Method API Docs

Request Errors

The request to the /webhooks/{webhook_id} endpoint failed. These are the sub_type that can be returned.

`INVALID_REQUEST`

The request body failed basic validation for the specific API endpoint.

`NOT_FOUND`

The requested resource does not exist.

`INVALID_WEBHOOK_STATUS`

The webhook status is invalid. Valid statuses are active and disabled.

`INVALID_WEBHOOK_URL`

The webhook url must be a valid HTTPS URL that does not point to internal or private addresses.

`MAX_ACTIVE_WEBHOOKS_EXCEEDED`

The maximum number of active webhooks for this event type has been reached.

`MAX_WEBHOOK_METADATA_SIZE_EXCEEDED`

The maximum metadata object size of 1KB was exceeded.

`WEBHOOK_ALREADY_EXISTS`

An active webhook already exists for this url and type combination.

`WEBHOOK_AUTH_TOKEN_AND_HMAC_SECRET_SAME`

The auth_token and hmac_secret cannot have the same value.

`WEBHOOK_PERMANENTLY_DELETED`

The status of a permanently deleted webhook cannot be updated.

Resource Errors

Method changes a Webhook’s status automatically when a delivery fails 5 times (the initial attempt and all retries) and more than 40% of the Webhook’s delivery attempts within the rolling 24-hour window have failed. Within a team-configured grace period the status becomes requires_attention (codes 25006–25009) and delivery continues; outside it, the Webhook is disabled (codes 25001–25004). Errors set on a webhook’s error property for processes that are unsuccessful.

`25001 – WEBHOOK_DISABLED_FAILED_OTHER`

There were 5 consecutive failures when posting to the webhook url provided where error was not a 4XX, 5XX error, or a timeout.

Causes

This could happen for a variety of reason types, please reach out to the team for more specific information.

{
  "type": "WEBHOOK_DISABLED",
  "code": 25001,
  "sub_type": "WEBHOOK_DISABLED_FAILED_OTHER",
  "message": "Webhook automatically disabled after failing 5 times to connect. Error was not 4XX or 5XX type."
}

Resolution

The webhook will be disabled and will not proceed in posting again to the provided url.

`25002 – WEBHOOK_DISABLED_RECEIVED_4XX_ERROR`

The webhook specifically received 4XX type errors when posting.

Causes

Invalid resource URL
Permission denied
Forbidden

{
  "type": "WEBHOOK_DISABLED",
  "code": 25002,
  "sub_type": "WEBHOOK_DISABLED_RECEIVED_4XX_ERROR",
  "message": "Webhook failed 5 times with a client error (4XX type)."
}

Resolution

The webhook will be disabled and will not proceed in posting again to the provided url.

`25003 – WEBHOOK_DISABLED_RECEIVED_5XX_ERROR`

The webhook specifically received 5XX type errors when posting.

Causes

Internal server error (from webhook url)
Not implemented
Bad Gateway
Server unavailable
Gateway timeout

{
  "type": "WEBHOOK_DISABLED",
  "code": 25003,
  "sub_type": "WEBHOOK_DISABLED_RECEIVED_5XX_ERROR",
  "message": "Webhook failed 5 times with a server error (5XX type)."
}

Resolution

The webhook will be disabled and will not proceed in posting again to the provided url.

`25004 – WEBHOOK_DISABLED_TIMEOUT_ON_RESPONSE`

When posting a information to a webhook url, our API did not receive a valid response in the 5 second period.

Causes

The timeout could happen for a variety of reasons:

Bad network or firewall config
Long processing time on webhook receiver side

{
  "type": "WEBHOOK_DISABLED",
  "code": 25004,
  "sub_type": "WEBHOOK_DISABLED_TIMEOUT_ON_RESPONSE",
  "message": "Webhook failed 5 times in receiving a response back from the webhook url provided. Expected response time is 5 seconds."
}

Resolution

The webhook will be disabled and will not proceed in posting again to the provided url. If you’ve timed out, check network configs to allow method servers to hit your webhook endpoint. Also confirm that after a payload has been posted to the webhook receiving url that successful responses are able to respond back in under 5 seconds. Typically this can be achieved by queuing the webhook data on your side and then immediately sending a 2xx response back, then processing the webhook information asynchronously.

`25005 – WEBHOOK_DISABLED_BY_USER`

The Webhook was manually disabled.

Causes

The Webhook’s status was set to disabled through the Update a Webhook endpoint.

{
  "type": "WEBHOOK_DISABLED",
  "code": 25005,
  "sub_type": "WEBHOOK_DISABLED_BY_USER",
  "message": "Webhook was manually disabled by the user."
}

Resolution

Set the Webhook’s status back to active when you want to resume deliveries.

`25006 – WEBHOOK_REQUIRES_ATTENTION_FAILED_OTHER`

The Webhook entered requires_attention after failing 5 times with an error that was not a 4XX or 5XX response.

{
  "type": "WEBHOOK_REQUIRES_ATTENTION",
  "code": 25006,
  "sub_type": "WEBHOOK_REQUIRES_ATTENTION_FAILED_OTHER",
  "message": "Webhook requires attention after failing 5 times to connect. Error was not 4XX or 5XX type."
}

Resolution

The Webhook continues to receive events while in requires_attention. Investigate and fix the endpoint to avoid the Webhook being disabled.

`25007 – WEBHOOK_REQUIRES_ATTENTION_RECEIVED_4XX_ERROR`

The Webhook entered requires_attention after failing 5 times with a client error (4XX type).

{
  "type": "WEBHOOK_REQUIRES_ATTENTION",
  "code": 25007,
  "sub_type": "WEBHOOK_REQUIRES_ATTENTION_RECEIVED_4XX_ERROR",
  "message": "Webhook requires attention after failing 5 times with a client error (4XX type)."
}

Resolution

The Webhook continues to receive events while in requires_attention. Investigate and fix the endpoint to avoid the Webhook being disabled.

`25008 – WEBHOOK_REQUIRES_ATTENTION_RECEIVED_5XX_ERROR`

The Webhook entered requires_attention after failing 5 times with a server error (5XX type).

{
  "type": "WEBHOOK_REQUIRES_ATTENTION",
  "code": 25008,
  "sub_type": "WEBHOOK_REQUIRES_ATTENTION_RECEIVED_5XX_ERROR",
  "message": "Webhook requires attention after failing 5 times with a server error (5XX type)."
}

Resolution

The Webhook continues to receive events while in requires_attention. Investigate and fix the endpoint to avoid the Webhook being disabled.

`25009 – WEBHOOK_REQUIRES_ATTENTION_TIMEOUT_ON_RESPONSE`

The Webhook entered requires_attention after failing 5 times to respond within the 5-second window.

{
  "type": "WEBHOOK_REQUIRES_ATTENTION",
  "code": 25009,
  "sub_type": "WEBHOOK_REQUIRES_ATTENTION_TIMEOUT_ON_RESPONSE",
  "message": "Webhook requires attention after failing 5 times in receiving a response back from the webhook url provided. Expected response time is 5 seconds."
}

Resolution

The Webhook continues to receive events while in requires_attention. Respond with a 2xx status code within 5 seconds, processing webhook data asynchronously.

​Request Errors

​INVALID_REQUEST

​NOT_FOUND

​INVALID_WEBHOOK_STATUS

​INVALID_WEBHOOK_URL

​MAX_ACTIVE_WEBHOOKS_EXCEEDED

​MAX_WEBHOOK_METADATA_SIZE_EXCEEDED

​WEBHOOK_ALREADY_EXISTS

​WEBHOOK_AUTH_TOKEN_AND_HMAC_SECRET_SAME

​WEBHOOK_PERMANENTLY_DELETED

​Resource Errors

​25001 – WEBHOOK_DISABLED_FAILED_OTHER

​Causes

​Resolution

​25002 – WEBHOOK_DISABLED_RECEIVED_4XX_ERROR

​Causes

​Resolution

​25003 – WEBHOOK_DISABLED_RECEIVED_5XX_ERROR

​Causes

​Resolution

​25004 – WEBHOOK_DISABLED_TIMEOUT_ON_RESPONSE

​Causes

​Resolution

​25005 – WEBHOOK_DISABLED_BY_USER

​Causes

​Resolution

​25006 – WEBHOOK_REQUIRES_ATTENTION_FAILED_OTHER

​Resolution

​25007 – WEBHOOK_REQUIRES_ATTENTION_RECEIVED_4XX_ERROR

​Resolution

​25008 – WEBHOOK_REQUIRES_ATTENTION_RECEIVED_5XX_ERROR

​Resolution

​25009 – WEBHOOK_REQUIRES_ATTENTION_TIMEOUT_ON_RESPONSE

​Resolution

Request Errors

`INVALID_REQUEST`

`NOT_FOUND`

`INVALID_WEBHOOK_STATUS`

`INVALID_WEBHOOK_URL`

`MAX_ACTIVE_WEBHOOKS_EXCEEDED`

`MAX_WEBHOOK_METADATA_SIZE_EXCEEDED`

`WEBHOOK_ALREADY_EXISTS`

`WEBHOOK_AUTH_TOKEN_AND_HMAC_SECRET_SAME`

`WEBHOOK_PERMANENTLY_DELETED`

Resource Errors

`25001 – WEBHOOK_DISABLED_FAILED_OTHER`

Causes

Resolution

`25002 – WEBHOOK_DISABLED_RECEIVED_4XX_ERROR`

Causes

Resolution

`25003 – WEBHOOK_DISABLED_RECEIVED_5XX_ERROR`

Causes

Resolution

`25004 – WEBHOOK_DISABLED_TIMEOUT_ON_RESPONSE`

Causes

Resolution

`25005 – WEBHOOK_DISABLED_BY_USER`

Causes

Resolution

`25006 – WEBHOOK_REQUIRES_ATTENTION_FAILED_OTHER`

Resolution

`25007 – WEBHOOK_REQUIRES_ATTENTION_RECEIVED_4XX_ERROR`

Resolution

`25008 – WEBHOOK_REQUIRES_ATTENTION_RECEIVED_5XX_ERROR`

Resolution

`25009 – WEBHOOK_REQUIRES_ATTENTION_TIMEOUT_ON_RESPONSE`

Resolution