Listen for Transaction webhooks to learn when transactions are ready for retrieval or when transactions have been updated.
Webhooks are a critical part of the Transactions product, as Plaid uses webhooks to tell you when transactions are ready to be retrieved, when new transactions have been added, or when old ones have changed. This guide will explain how to handle all four transaction webhooks to make sure you have access to a user's full and 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.
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.
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 field of your most recent existing transaction, and stop adding transactions once you've found a match. 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
Example code in Plaid Pattern
For a real-life example of handling webhooks that illustrates how to handle all four transaction webhook types, 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, if your user just fixed an outdated password that was preventing your app from fetching transactions for several days, you might want to immediately check for removed and updated transactions. Or you might want to build a refresh button in your app that allows your user to check for updated transactions on-demand. Calling the
/transactions/refresh endpoint will force
TRANSACTIONS_REMOVED to check for updates and fire if there are any changes for them to report. It's a recommended practice to call
/transactions/refresh when your user exits the Link flow in update mode. When fetching transactions after updating an Item in Link, you should fetch transactions for at least 1-2 days beyond the number of days the Item was in an error state, or at least 90 days of transactions if you aren't tracking the number of days that the Item was disconnected.
Before you launch your app to the world in Production, it's a good idea to add logic that verifies Plaid's webhooks to make sure that the webhook is coming from Plaid, and not from a third party impersonator. You can do this by verifying the webhook using the