> ## Documentation Index
> Fetch the complete documentation index at: https://docs.methodfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Errors

## 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.

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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](/2026-03-30/reference/webhooks/update) endpoint.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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).

```json theme={null}
{
  "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).

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.