Sample - Plaid API
POST/beta/webhook_events/list

List webhook events

Lists webhook events sent to the calling client during the last seven days. Use cursor for subsequent pages or start_time for the initial time boundary, and combine array filters with AND across fields and OR within each array. Results are ordered by sent_time ascending and include delivery information for deduplication by webhook_message_id.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

9 body fields

Cursor-paginated filters for retrieving webhook events retained from the last seven days.

client_idstringoptional
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.
secretstringoptional
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.
cursorstringoptional
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`: sending both returns `INVALID_FIELD`. Callers should send only one.
start_timestringoptional
ISO-8601 timestamp. Returns webhook events with `sent_time` greater than or equal to this value. Must not be earlier than the 7-day retention window. Mutually exclusive with `cursor`: sending both returns `INVALID_FIELD`. Omit to begin from the oldest retained event. Callers should send only one of `cursor` or `start_time`.
countintegeroptional
Page size. Default 100, maximum 100.
Default:100
webhook_typesarray<string>optional
Filter by webhook type. Multiple values are OR'd. Combined with other filters using AND. Values are case-sensitive and match the webhook types Plaid sends (`SCREAMING_SNAKE`, for example `ITEM` or `AUTH`).
webhook_codesarray<string>optional
Filter by webhook code. Multiple values are OR'd. Combined with other filters using AND. Values are case-sensitive and match the webhook codes Plaid sends (`SCREAMING_SNAKE`, for example `ERROR`).
item_idsarray<string>optional
Filter to specific Items. Multiple values are OR'd. Combined with other filters using AND. Values are case-sensitive and match the Item IDs Plaid sends.
delivery_statusesarray<string>optional
Filter by delivery status. Returns webhook events whose latest delivery state matches any of the supplied values. Combined with other filters using AND.

2 status codes
200Returns an ascending list of webhook events, a `has_more` indicator, a `next_cursor` for continued pagination, and a unique `request_id`.
webhook_eventsarray<object>required
Webhook events sent to the calling client.
has_morebooleanrequired
Indicates whether another page of webhook events is available.
next_cursorstringrequired
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_idstringrequired
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
defaultError response
error_typestringrequired
A broad categorization of the error. Safe for programmatic use.
Allowed:INVALID_REQUESTINVALID_RESULTINVALID_INPUTINSTITUTION_ERRORRATE_LIMIT_EXCEEDEDAPI_ERRORITEM_ERRORASSET_REPORT_ERRORBASE_REPORT_ERRORRECAPTCHA_ERROROAUTH_ERRORPAYMENT_ERROR
error_codestringrequired
The particular error code. Safe for programmatic use.
error_code_reasonstringoptional
The specific reason for the error code. Currently, reasons are only supported for OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user's OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user's OAuth connection to this institution is invalid because the user revoked their connection.
error_messagestringrequired
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_messagestringrequired
A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use.
request_idstringoptional
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causesarrayoptional
In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object.
statusintegeroptional
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_urlstringoptional
The URL of a Plaid documentation page with more information about the error
suggested_actionstringoptional
Suggested steps for resolving the error
required_account_subtypesarray<string>optional
A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product.
provided_account_subtypesarray<string>optional
A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product.

Error handling

Use only one of cursor or start_time; they are mutually exclusive, and start_time must be within the seven-day retention window. count must be between 1 and 100, cursor must not exceed 512 characters, and delivery_statuses accepts only PENDING, DELIVERED, or FAILED.