Webhooks

API reference for webhooks

Prefer to learn by watching? A video guide is available for this topic.

Introduction

Plaid uses webhooks to send programmatic updates about your user’s Items. Webhooks are configured via the webhook parameter of /link/token/create when adding an Item. The URL must be in the standard format of http(s)://(www.)domain.com/ and, if https, must have a valid SSL certificate.

Plaid sends POST payloads with raw JSON to your webhook URL from one of the following IP addresses:

  • 52.21.26.131
  • 52.21.47.157
  • 52.41.247.19
  • 52.88.82.239

Note that these IP addresses are subject to change.

If there is a non-200 response or no response within 10 seconds from the webhook endpoint, Plaid will retry sending the webhook up to two times with a few minutes in between each webhook.

Check the Logs section in the Dashboard to debug any issues when setting up your webhooks.

To test your webhook handling in the Sandbox environment, you can use the /sandbox/item/fire_webhook endpoint to fire a webhook on demand. If you don't have a webhook endpoint configured yet, for testing purposes, you can also use a tool such as Request Bin to quickly and easily set up a webhook listener endpoint to provide to /sandbox/public_token/create. When directing webhook traffic to third-party tools, make sure you are using Plaid's Sandbox environment and not sending out live data.

Item webhooks

Webhooks are used to communicate changes to an Item, such as an updated webhook, or errors encountered with an Item. The error typically requires user action to resolve, such as when a user changes their password. All Item webhooks have a webhook_type of ITEM.

In this section
ITEM: ERRORItem has entered an error state
ITEM: PENDING_EXPIRATIONItem access is about to expire
ITEM: USER_PERMISSION_REVOKEDThe user has revoked access to an Item
ITEM: WEBHOOK_UPDATE_ACKNOWLEDGEDItem webhook URL updated

ITEM: ERROR

ITEM: PENDING_EXPIRATION

ITEM: USER_PERMISSION_REVOKED

ITEM: WEBHOOK_UPDATE_ACKNOWLEDGED

Transaction webhooks

You can receive notifications via a webhook whenever there are new transactions associated with an Item, including when Plaid’s initial and historical transaction pull are completed. All webhooks related to transactions have a webhook_type of TRANSACTIONS.

In this section
TRANSACTIONS: INITIAL_UPDATEInitial transactions ready
TRANSACTIONS: HISTORICAL_UPDATEHistorical transactions ready
TRANSACTIONS: DEFAULT_UPDATENew transactions available
TRANSACTIONS: TRANSACTIONS_REMOVEDDeleted transactions detected

TRANSACTIONS: INITIAL_UPDATE

TRANSACTIONS: HISTORICAL_UPDATE

TRANSACTIONS: DEFAULT_UPDATE

TRANSACTIONS: TRANSACTIONS_REMOVED

Auth webhooks

Updates are sent for Items that are linked using automated and manual micro-deposits. All webhooks related to Auth have a webhook_type of AUTH.

When an automated micro-deposit is created, Plaid sends a webhook upon successful verification. If verification does not succeed after ten days for either an automated micro-deposit, Plaid sends a VERIFICATION_EXPIRED webhook. If you attempt to retrieve an automated micro-deposit Item before verification succeeds, you’ll receive a response with the HTTP status code 400 and a Plaid error code of PRODUCT_NOT_READY. Note that Plaid does not send webhooks to report on the status of of Same-Day micro-deposits.

In this section
AUTH: AUTOMATICALLY_VERIFIEDItem has been verified
AUTH: VERIFICATION_EXPIREDItem verification has failed

AUTH: AUTOMATICALLY_VERIFIED

AUTH: VERIFICATION_EXPIRED

Assets webhooks

Updates are sent to indicate that an Asset Report has been generated or that the generation process has failed. All webhooks related to Assets have a webhook_type of ASSETS.

In this section
ASSETS: PRODUCT_READYAsset Report generation has completed
ASSETS: ERRORAsset Report generation has failed

ASSETS: PRODUCT_READY

ASSETS: ERROR

Investments webhooks

Updates are sent to indicate that new investment transactions are available.

In this section
HOLDINGS: DEFAULT_UPDATENew holdings available
INVESTMENTS_TRANSACTIONS: DEFAULT_UPDATENew transactions available

HOLDINGS: DEFAULT_UPDATE

INVESTMENTS_TRANSACTIONS: DEFAULT_UPDATE

Payment Initiation webhooks

Updates are sent to indicate that the status of an initiated payment has changed. All Payment Initiation webhooks have a webhook_type of PAYMENT_INITIATION.

In this section
PAYMENT_INITIATION: PAYMENT_STATUS_UPDATEThe status of a payment has changed

PAYMENT_INITIATION: PAYMENT_STATUS_UPDATE

Bank Transfers webhooks

Updates are sent to indicate that new bank transfer events are available. See the Bank Transfers webhook page for an integration guide.

In this section
BANK_TRANSFERS: BANK_TRANSFERS_EVENTS_UPDATENew bank transfer events available

BANK_TRANSFERS: BANK_TRANSFERS_EVENTS_UPDATE