--- 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. - `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', required — A broad categorization of the error. Safe for programmatic use. - `error_code` string, required — The particular error code. Safe for programmatic use. - `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 the Assets 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 have gone through consent collection for the Item. Only present for those enabled in the [Data Transparency](https://plaid.com/docs/link/data-transparency-messaging-migration-guide) beta. If you are not enrolled in Data Transparency, this field is not used. - `consent_expiration_time` string, date-time, nullable, required — The RFC 3339 timestamp after which the consent provided by the end user will expire. Upon consent expiration, the item will enter the `ITEM_LOGIN_REQUIRED` error state. To circumvent the `ITEM_LOGIN_REQUIRED` error and maintain continuous consent, the end user can reauthenticate via Link’s update mode in advance of the consent expiration time. Note - This is only relevant for certain OAuth-based institutions. For all other institutions, this field will be null. - `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-04-17** `943c632a075c` — 4 warning - added the new `profile` enum value to the `item/available_products/items/` response property for the response status `200` - added the new `profile` enum value to the `item/billed_products/items/` response property for the response status `200` - added the new `profile` enum value to the `item/consented_products/items/` response property for the response status `200` - added the new `profile` enum value to the `item/products/items/` response property for the response status `200` - **2024-02-21** `5de70cc1e6ca` — 9 warning, 80 info - removed the optional property `item/auth_method` from the response with the `200` status - removed the optional property `item/error/error_code_reason` from the response with the `200` status - removed the optional property `item/error/provided_account_subtypes` from the response with the `200` status - removed the optional property `item/error/required_account_subtypes` from the response with the `200` status - …85 more [Change 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/a5b45bccb4e8/schema)