---
title: "Update Webhook URL"
method: POST
path: "/item/webhook/update"
tags: ["plaid"]
---

# Update Webhook URL

`POST /item/webhook/update`

The POST `/item/webhook/update` allows you to update the webhook URL associated with an Item. This request triggers a [`WEBHOOK_UPDATE_ACKNOWLEDGED`](https://plaid.com/docs/api/items/#webhook_update_acknowledged) webhook to the newly specified webhook URL.

## Request body

- ItemWebhookUpdateRequest — ItemWebhookUpdateRequest defines the request schema for `/item/webhook/update`
  - `client_id` string — Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body.
  - `secret` string — Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body.
  - `access_token` string, required — The access token associated with the Item data is being requested for.
  - `webhook` string, nullable — The new webhook URL to associate with the Item. To remove a webhook from an Item, set to `null`.

## Response `200`

OK

- ItemWebhookUpdateResponse — ItemWebhookUpdateResponse defines the response schema for `/item/webhook/update`
  - `item` Item, required — Metadata about the Item.
    - `item_id` string, required — The Plaid Item ID. The `item_id` is always unique; linking the same account at the same institution twice will result in two Items with different `item_id` values. Like all Plaid identifiers, the `item_id` is case-sensitive.
    - `institution_id` string, nullable — The Plaid Institution ID associated with the Item. Field is `null` for Items created via Same Day Micro-deposits.
    - `created_at` string, date-time — The date and time when the Item was created, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format.
    - `webhook` string, nullable, required — The URL registered to receive webhooks for the Item.
    - `error` PlaidError, nullable, required — Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead.
      - `error_type` 'INVALID_REQUEST' | 'INVALID_RESULT' | 'INVALID_INPUT' | 'INSTITUTION_ERROR' | 'RATE_LIMIT_EXCEEDED' | 'API_ERROR' | 'ITEM_ERROR' | 'ASSET_REPORT_ERROR' | 'RECAPTCHA_ERROR' | 'OAUTH_ERROR' | 'PAYMENT_ERROR' | 'BANK_TRANSFER_ERROR' | 'INCOME_VERIFICATION_ERROR' | 'MICRODEPOSITS_ERROR' | 'SANDBOX_ERROR' | 'PARTNER_ERROR' | 'TRANSACTIONS_ERROR' | 'TRANSACTION_ERROR' | 'TRANSFER_ERROR', required — A broad categorization of the error. Safe for programmatic use.
      - `error_code` string, required — The particular error code. Safe for programmatic use.
      - `error_code_reason` string, nullable — The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_REVOKED_TOKEN`: The user’s OAuth connection to this institution is invalid because the user revoked their connection.
      - `error_message` string, required — A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
      - `display_message` string, nullable, required — A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use.
      - `request_id` string — A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
      - `causes` unknown[] — In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will only be provided for the `error_type` `ASSET_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object.
        - unknown
      - `status` integer, nullable — The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
      - `documentation_url` string — The URL of a Plaid documentation page with more information about the error
      - `suggested_action` string, nullable — Suggested steps for resolving the error
    - `available_products` Products[], required — A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with `billed_products`.
    - `billed_products` Products[], required — A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with `available_products`. Note - `billed_products` is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as `balance`, will not appear here.
    - `products` Products[] — A list of products added to the Item. In almost all cases, this will be the same as the `billed_products` field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before `/asset_report/create` has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in `products` but not in `billed_products`.
    - `consented_products` Products[] — A list of products that the user has consented to for the Item via [Data Transparency Messaging](/docs/link/data-transparency-messaging-migration-guide). This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product.
    - `consented_use_cases` string[] — A list of use cases that the user has consented to for the Item via [Data Transparency Messaging](/docs/link/data-transparency-messaging-migration-guide). You can see the full list of use cases or update the list of use cases to request at any time via the Link Customization section of the [Plaid Dashboard](https://dashboard.plaid.com/link/data-transparency-v5).
    - `consented_data_scopes` ItemConsentedDataScope[] — A list of data scopes that the user has consented to for the Item via [Data Transparency Messaging](/docs/link/data-transparency-messaging-migration-guide). These are based on the `consented_products`; see the [full mapping](/docs/link/data-transparency-messaging-migration-guide/#data-scopes-by-product) of data scopes and products.
    - `consent_expiration_time` string, date-time, nullable, required — The date and time at which the Item's access consent will expire, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format
    - `update_type` 'background' | 'user_present_required', required — Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. `background` - Item can be updated in the background `user_present_required` - Item requires user interaction to be updated
  - `request_id` string, required — A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

## Changes

- **2024-10-09** `36052f62cce1` — 4 warning, 7 info
  - added the new `pay_by_bank` enum value to the `item/available_products/items/` response property for the response status `200`
  - added the new `pay_by_bank` enum value to the `item/billed_products/items/` response property for the response status `200`
  - added the new `pay_by_bank` enum value to the `item/consented_products/items/` response property for the response status `200`
  - added the new `pay_by_bank` enum value to the `item/products/items/` response property for the response status `200`
  - …7 more
- **2024-09-04** `a2c34406c317` — 9 warning, 1 info
  - added the new `PARTNER_ERROR` enum value to the `item/error/error_type` response property for the response status `200`
  - added the new `SANDBOX_ERROR` enum value to the `item/error/error_type` response property for the response status `200`
  - added the new `TRANSACTIONS_ERROR` enum value to the `item/error/error_type` response property for the response status `200`
  - added the new `TRANSACTION_ERROR` enum value to the `item/error/error_type` response property for the response status `200`
  - …6 more
- …earlier changes not shown

[Full history](https://skmtc.dev/plaid/apis/the-plaid-api/changes/item/webhook/update/post.md)

---

[API](https://skmtc.dev/plaid/apis/the-plaid-api.md) · [All operations](https://skmtc.dev/plaid/apis/the-plaid-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/plaid/the-plaid-api/revisions/36052f62cce1/schema)