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.
Webhooks are typically configured via the
webhook parameter of
/link/token/create, although some webhooks used in contexts where Link sessions are not required, such as Bank Transfer webhooks and Wallet transaction webhooks, are configured via the Plaid Dashboard instead. When specifying a webhook, 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.
Best practices for applications using webhooks
You should design your application to handle duplicate, and out-of-order webhooks. Ensure idempotency on actions you take when receiving a webhook. If you drive application state with webhooks, ensure your code doesn't rely on a specific order of webhook receipt.
If you (or Plaid) experience downtime for longer than Plaid's retry period, you will lose webhooks. If you use webhooks for state transitions, ensure your application can self-heal by requesting Item state from Plaid's other endpoints if a webhook is not received within a window. All data present in webhooks is also present in our other APIs.
It's best to keep your receiver as simple as possible, such as a receiver whose only job is to write the webhook into a queue or reliable storage. This is important for two reasons. First, if the receiver does not respond within 10 seconds, the delivery is considered failed. Second, because webhooks can arrive at unpredictable rates. Therefore if you do a lot of work in your receiver - e.g. generating and sending an email - spikes are likely to overwhelm your downstream services, or cause you to be rate-limited if the downstream is a third-party.
Testing webhooks in Sandbox
Webhooks will fire as normal in the Sandbox environment, with the exception of Transfer webhooks. For testing purposes, you can also use
/sandbox/transfer/fire_webhook 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. 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.