You can receive notifications regarding transactions from Plaid via webhooks when the following occurs:
- an initial transaction pull has completed
- new transactions are associated with an
Item
- transactions have been removed from an
Item
an historical transaction pull has completed
INITIAL_UPDATE
Plaid fires the INITIAL_UPDATE
webhook when an Item's
initial transaction pull has finished.
Example INITIAL_UPDATE
webhook:
{
"webhook_type": "TRANSACTIONS",
"webhook_code": "INITIAL_UPDATE",
"item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
"error": null,
"new_transactions": 19
}
The initial transaction pull occurs when creating an Item
with Transactions – specifically, when Plaid Link's product
array is initialized with 'transactions'
. If an Item
was not initialized with 'transactions'
as a product and is later used to make a /transactions/get
request, you will be returned a PRODUCT_NOT_READY
error, but the INITIAL_UPDATE
and HISTORICAL_UPDATE
webhooks will fire shortly thereafter.
HISTORICAL_UPDATE
After the initial transaction pull is finished, Plaid will begin the historical transaction pull. Plaid fires the HISTORICAL_UPDATE
webhook when the historical transaction pull for an Item
is finished.
Example HISTORICAL_UPDATE
webhook:
{
"webhook_type": "TRANSACTIONS",
"webhook_code": "HISTORICAL_UPDATE",
"item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
"error": null,
"new_transactions": 231
}
The length of time required for a historical pull is determined by the volume of an Item's accounts and transactions. An Item
with a large number of accounts – such as a business bank account with many credit cards, each of which has many transactions per day – will take longer than an account with one or two accounts with few transactions per day.
The historical transaction pull retrieves as much historical data as is available for the Item
at the financial institution.
DEFAULT_UPDATE
The DEFAULT_UPDATE
webhook is fired when Plaid fetches new pending or posted transactions for an Item
.
Example DEFAULT_UPDATE
webhook:
{
"webhook_type": "TRANSACTIONS",
"webhook_code": "DEFAULT_UPDATE",
"item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
"error": null,
"new_transactions": 3
}
Plaid routinely checks for transaction updates, but a DEFAULT_UPDATE
will only fire when new transaction data is available. When a DEFAULT_UPDATE
webhook is triggered, you may make a /transactions/get
request to retrieve the latest transaction data. Please note that the regularity of transaction data updates can vary across financial institutions.
TRANSACTIONS_REMOVED
Plaid sends a TRANSACTIONS_REMOVED
webhook when pending or posted transactions have been removed from our system.
Example TRANSACTIONS_REMOVED
webhook:
{
"webhook_type": "TRANSACTIONS",
"webhook_code": "TRANSACTIONS_REMOVED",
"item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
"removed_transactions": ["yBVBEwrPyJs8GvR77N7QTxnGg6wG74H7dEDN6", "kgygNvAVPzSX9KkddNdWHaVGRVex1MHm3k9no"],
"error": null
}
Pending transactions can be removed for the following reasons:
- They were matched to a posted transaction.
- They no longer appear in the data we get from the institution, which may occur when transactions are cancelled by the bank or payment processor.
To learn more about pending transactions, see the Pending transaction overview.
Posted transactions are removed from Plaid's system when the transaction was removed by the institution.
You will receive a TRANSACTIONS_REMOVED
webhook with the transaction_id
s for each removed transaction. Future /transactions/get
requests will not return previously removed transactions.