Webhook events
Recover webhooks your endpoint missed
/beta/webhook_events/list
List webhook events
/beta/webhook_events/list returns the webhooks Plaid sent to your account in the last 7 days, including webhooks that weren't delivered. Use it to recover webhooks your endpoint missed. Events are returned oldest first.
TRANSACTIONS webhooks are not included. To recover Transactions updates, use /transactions/sync.
To page through events, omit cursor on your first request, then pass the previous response's next_cursor on each later request. Store next_cursor even when has_more is false, so your next poll returns only newer events.
Filters are optional. An event matches a filter if it matches any of the filter's values, and must match every filter you provide.
Events older than 7 days are not retained. If your cursor or start_time is older than that, the request fails with WEBHOOK_EVENTS_CURSOR_EXPIRED or WEBHOOK_EVENTS_START_TIME_OUT_OF_RANGE.
This endpoint is in beta and may change in backwards-incompatible ways. Send feedback to building@plaid.com.
Request fields
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
The next_cursor from a previous /beta/webhook_events/list response. Omit on your first request. If provided, start_time is ignored.
512 Return events sent at or after this time, in ISO 8601 format. Must be within the last 7 days. Ignored if cursor is provided. If you omit both cursor and start_time, results start with the oldest retained event.
date-time The maximum number of webhook events to return. Fewer events may be returned even when more are available; use has_more to determine whether to request another page.
1 100 100 Return only events with these webhook types, for example ITEM. Case-sensitive.
Return only events with these webhook codes, for example ERROR. Case-sensitive.
Return only events for these Items.
Return only events with these delivery statuses.
PENDING, DELIVERED, FAILED// Provide a cursor you've previously stored, or leave it
// undefined on the first call.
let cursor = loadSavedCursor();
let hasMore = true;
while (hasMore) {
const request: BetaWebhookEventsListRequest = {
cursor: cursor,
count: 100,
};
const response = await plaidClient.betaWebhookEventsList(request);
const data = response.data;
for (const event of data.webhook_events) {
if (!alreadyProcessed(event.webhook_message_id)) {
handleWebhookEvent(event);
}
}
hasMore = data.has_more;
// Persist next_cursor even when has_more is false, then reuse
// it on the next poll so you only receive newer events.
cursor = data.next_cursor;
saveCursor(cursor);
}
Response fields
Webhook events for your account.
The ID of this webhook event. It stays the same across requests, so you can use it to skip events you've already handled. Include it when contacting Support.
The webhook type.
The webhook code.
The Item ID associated with the webhook, if any.
The time Plaid sent the webhook.
date-time The JSON body Plaid sent to the webhook destination.
The destination URL Plaid sent the webhook to.
The current delivery status of the webhook.
PENDING: Plaid hasn't recorded a successful delivery and may retry. The webhook may have been delivered even if its status is PENDING.
DELIVERED: Your endpoint returned a 2xx response.
FAILED: Plaid stopped retrying without receiving a 2xx response.
PENDING, DELIVERED, FAILEDThe most recent HTTP status code returned by the destination, if any.
Number of delivery attempts Plaid has made for this webhook.
The time of the most recent delivery attempt. Null if Plaid hasn't attempted delivery yet.
date-time Indicates whether another page of webhook events is available.
The cursor to send as cursor in your next request. Store it even when has_more is false.
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
{
"webhook_events": [
{
"webhook_message_id": "whmsg_4tQ9pNzL2vBxYK",
"webhook_type": "ITEM",
"webhook_code": "PENDING_EXPIRATION",
"item_id": "abc123",
"sent_time": "2026-07-21T14:32:00Z",
"payload": {
"webhook_type": "ITEM",
"webhook_code": "PENDING_EXPIRATION"
},
"destination_url": "https://client.example.com/webhook",
"delivery_status": "DELIVERED",
"last_http_status_code": 200,
"attempt_count": 1,
"last_attempt_time": "2026-07-21T14:32:01Z"
}
],
"has_more": true,
"next_cursor": "eyJzZW50X3RpbWUiOiIyMDI2LTA3LTIxVDE0OjMyOjAwWiIsIndlYmhvb2tfbWVzc2FnZV9pZCI6IndobXNnXzR0UTlwTnpMMnZCeFlLIn0",
"request_id": "4zlKapIkTm8p5KM"
}