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 (especially those used in contexts where Link tokens are not always required), such as Identity Verification webhooks, 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:

• 52.21.26.131
• 52.21.47.157
• 52.41.247.19
• 52.88.82.239

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.

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.

Webhooks will fire as normal in the Sandbox environment, with the exception of Transfer webhooks. For testing purposes, you can also use /sandbox/item/fire_webhook, /sandbox/income/fire_webhook, or /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.

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.