API reference for webhooks
Prefer to learn by watching? Our video tutorial walks you through the basics of incorporating Plaid webhooks into your application.
Introduction to webhooks
A webhook is an HTTP request used to provide push notifications. Plaid sends webhooks to programmatically inform you about changes to Plaid Items or the status of asynchronous processes. For example, Plaid will send a webhook when an Item is in an error state or has additional data available, or when a non-blocking process (like gathering transaction data or verifying a bank account via micro-deposits) is complete.
To receive Plaid webhooks, set up a dedicated endpoint on your server as a webhook listener that can receive POST requests, then provide this endpoint URL to Plaid as described in the next section. You can also test webhooks without setting up your own endpoint following the instructions in Testing webhooks in Sandbox.
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.
To view response codes and debug any issues with webhook setup, see the Logs section in the Dashboard.
Plaid sends POST payloads with raw JSON to your webhook URL from one of the following IP addresses:
Note that these IP addresses are subject to change.
You can optionally verify webhooks to ensure they are from Plaid. For more information, see webhook verification.
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.
Testing webhooks in Sandbox
Webhooks will fire as normal in the Sandbox environment. For testing purposes, you can also use the
/sandbox/item/fire_webhook endpoint to fire a webhook on demand. If you don't have a webhook endpoint configured yet, 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.
Example in Plaid Pattern
For real-life examples of handling webhooks that illustrate how to handle sample transactions and Item webhooks, see handleTransactionsWebhook.js and handleItemWebhook.js These files contain webhook handling code for the Node-based Plaid Pattern sample app.