Sign in
latestOpenAPI 3.0.0raw.githubusercontent.com2026-08-173512,4063.0 MB

e536704a333f

plaid

List webhook events

The /beta/webhook_events/list endpoint returns webhook events Plaid sent to the calling client within the last 7 days. Results are ordered by sent_time ascending and cursor paginated so clients can recover missed webhook deliveries and deduplicate on webhook_message_id.

Filtering is optional. When multiple filter fields are set (webhook_types, webhook_codes, item_ids, delivery_statuses), they are combined with AND across fields and OR within each array (for example, webhook_types: ["TRANSACTIONS", "ITEM"] matches either type).

Recommended pagination workflow:

  1. First call: omit cursor, and optionally set start_time within the last 7 days (or omit start_time to begin at the oldest retained event).
  2. Subsequent calls: pass next_cursor as cursor. Do not send start_time with cursor — the two fields are mutually exclusive.
  3. Persist next_cursor even when has_more is false, then reuse it on the next poll so you only receive events newer than what you have already seen.
  4. If a stored cursor is older than the 7-day retention window, the API returns WEBHOOK_EVENTS_CURSOR_EXPIRED; restart with a start_time within the last 7 days. Events older than the retention window are no longer available.
post/beta/webhook_events/list

Request body

client_idstring

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.

secretstring

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.

cursorstring

Opaque cursor from a prior /beta/webhook_events/list response next_cursor. Use this on subsequent requests to continue forward. Mutually exclusive with start_time.

start_timestring date-time nullable

ISO-8601 timestamp. Returns webhook events with sent_time greater than or equal to this value. Must fall within the last 7 days (the retention window). Mutually exclusive with cursor. Omit to begin from the oldest retained event.

countinteger nullable

Page size. Default 100, maximum 100.

webhook_typesstring[]

Filter by webhook type. Multiple values are OR'd. Combined with other filters using AND.

webhook_codesstring[]

Filter by webhook code. Multiple values are OR'd. Combined with other filters using AND.

item_idsstring[]

Filter to specific Items. Multiple values are OR'd. Combined with other filters using AND.

delivery_statusesWebhookEventDeliveryStatus[]

Filter by delivery status. Returns webhook events whose latest delivery state matches any of the supplied values. Combined with other filters using AND.

Response

OK

has_moreboolean required

Indicates whether another page of webhook events is available.

next_cursorstring required

Cursor to pass as cursor on a later /beta/webhook_events/list request to continue forward. Persist and reuse this value even when has_more is false so the next poll only returns newer events.

request_idstring required

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.