Listen for Transaction webhooks to learn when transactions are ready for retrieval or when transactions have been updated.
Webhooks are a useful part of the Transactions product that notifies you when Plaid has new or updated transaction information. This guide will explain how to use webhooks to make sure you have up-to-date transaction history.
Configuring Link for transactions webhooks
Before you can listen to webhooks, you must first set up an endpoint and tell Plaid where to find it.
To tell Plaid where to send its webhooks, send your webhook endpoint URL as an optional argument via the
webhook parameter to
You must also initialize your Item with Transactions by including
transactions in the
products array provided to
/link/token/create. If you do not do this, Plaid will not attempt to retrieve any transactions for your Item until after
/transactions/get is called for the first time. For more information, see Choosing when to initialize products.
Integrating the update notification webhook
/transactions/sync is called for the first time on an Item,
SYNC_UPDATES_AVAILABLE webhooks will begin to be sent to the configured destination endpoint.
This webhook will fire whenever any change has happened to the Item's transactions. The changes can then be retrieved by calling
/transactions/sync with the
cursor from your last sync call to this Item.
If at least 30 days of history is available with an update, the
initial_update_complete parameter in the body of the
SYNC_UPDATES_AVAILABLE webhook will be
historical_update_complete will be
true if the full history (up to 24 months) is available.
For a real-life example that illustrates how to handle this webhook, see handleTransactionsWebhook.js, which contains the webhook handling code for the Node-based Plaid Pattern app.
Forcing transactions refresh
Sometimes, checking for transactions a few times a day is not good enough. For example, you might want to build a refresh button in your app that allows your user to check for updated transactions on-demand. To accomplish this, you can use the
/transactions/refresh product. After a successful call to
/transactions/refresh, if there are new updates,
SYNC_UPDATES_AVAILABLE will be fired (along with
DEFAULT_UPDATE and, if applicable,
Instructions for integrations using /transactions/get
The content in this section and below applies only to existing integrations using the
/transactions/get endpoint. It is recommended that any new integrations use
/transactions/sync instead of
/transactions/get, for easier and simpler handling of transaction state changes. For information on migrating an existing
/transactions/get integration to
/transactions/sync, see the Transactions sync migration guide.
When you first connect an Item in Link, transactions data will not immediately be available.
HISTORICAL_UPDATE are both webhooks that fire shortly after an Item has been initially linked
and initialized with the Transactions product. These webhooks will let you know when your transactions
INITIAL_UPDATE fires first, after Plaid has successfully pulled 30 days of transactions for an Item.
HISTORICAL_UPDATE webhook fires next, once all historical transactions data is available. It typically takes about
10 seconds for
INITIAL_UPDATE to fire and 1-2 minutes for
HISTORICAL_UPDATE to fire.
If you attempt to call
INITIAL_UPDATE has fired, you will get a
PRODUCT_NOT_READY error. If you attempt to call
has fired, but before
HISTORICAL_UPDATE has fired, you will only be able to receive the last 30 days of
transaction data. If you did not initialize the Item with Transactions, your first call to
will result in a
PRODUCT_NOT_READY error and kick off the process of readying transactions. You can then
listen for the
HISTORICAL_UPDATE webhooks to begin receiving transactions.
Plaid fires two types of webhooks that provide information about changes to transaction data:
Adding new transactions
DEFAULT_UPDATE webhook fires when new transactions are available. Typically, Plaid will check for transactions once every 6 hours, but may check less frequently (such as once every 24 hours) depending on factors such as the institution and account type. If new transactions are available, the
DEFAULT_UPDATE webhook will fire.
To reflect up-to-date transactions for a user in your app, handle the
DEFAULT_UPDATE webhook by fetching more transactions. We recommend fetching about 7-14 days of transactions in response to
DEFAULT_UPDATE. This is typically enough history to ensure that you haven't missed any transactions, but not so much that performance or rate limiting is likely to be a problem.
Once you've fetched these transactions, you will need to identify which transactions are new and which are duplicates of existing data that you have. You should not rely on the number in the webhook's
new_transactions field to identify duplicates, since it can be unreliable. For example, new transactions may arrive between your receipt of the webhook and your call to
/transactions/get. Instead, compare the
transaction_id field of each newly fetched transaction to the
transaction_id fields of your existing transactions, and skip the ones that you already have. For an example, see Plaid Pattern.
Removing stale transactions
TRANSACTIONS_REMOVED webhook fires when transactions have been removed. The most common reason for this is in the case of pending transactions. In general, transactions start out as pending transactions and then move to the posted state one to two business days later. When Plaid detects that a transaction has moved from pending to posted state, the pending transaction as returned by
/transactions/get is not modified. Instead, the pending transaction is removed, and a new transaction is added, representing the posted transaction. For a detailed explanation of pending and posted transactions and how they are handled by Plaid, see Transaction states.
Pending transactions can also be removed when they are canceled by the bank or payment processor. A transaction may be removed if its details are changed by the bank so extensively that Plaid can no longer recognize the new and old versions of the transaction as being the same (e.g., a transaction amount and description both being changed simultaneously). In this case, the old transaction will be deleted and a new transaction with the new details will be added. This "transaction churn" can affect both pending and posted transactions.
TRANSACTIONS_REMOVED webhook contains the transaction IDs of the removed transactions, which you can use to identify and remove the corresponding transactions in your own application to avoid presenting duplicated or inaccurate data. If you encounter any problems with the webhook, you can also manually query transaction history for deleted transactions using logic similar to that recommended for handling the