Transactions webhooks

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.

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 /link/token/create.

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/sync or /transactions/get is called for the first time. For more information, see Choosing when to initialize products.

After /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 true. Similarly, 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.

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, TRANSACTIONS_REMOVED).

When you first connect an Item in Link, transactions data will not immediately be available. INITIAL_UPDATE and 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 are ready. INITIAL_UPDATE fires first, after Plaid has successfully pulled 30 days of transactions for an Item. The 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 /transactions/get before INITIAL_UPDATE has fired, you will get a PRODUCT_NOT_READY error. If you attempt to call /transactions/get after INITIAL_UPDATE 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 /transactions/get will result in a PRODUCT_NOT_READY error and kick off the process of readying transactions. You can then listen for the INITIAL_UPDATE or HISTORICAL_UPDATE webhooks to begin receiving transactions.

Updating transactions

Plaid fires two types of webhooks that provide information about changes to transaction data: DEFAULT_UPDATE and TRANSACTIONS_REMOVED.

Adding new transactions

The 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

The 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.

The 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 DEFAULT_UPDATE webhook.