---
title: "List webhook events"
method: POST
path: "/beta/webhook_events/list"
tags: ["plaid"]
---

# List webhook events

`POST /beta/webhook_events/list`

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.

## Request body

- BetaWebhookEventsListRequest — BetaWebhookEventsListRequest defines the request schema for `/beta/webhook_events/list`
  - `client_id` string — 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.
  - `secret` string — 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.
  - `cursor` string — 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_time` string, 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.
  - `count` integer, nullable — Page size. Default 100, maximum 100.
  - `webhook_types` string[] — Filter by webhook type. Multiple values are OR'd. Combined with other filters using AND.
  - `webhook_codes` string[] — Filter by webhook code. Multiple values are OR'd. Combined with other filters using AND.
  - `item_ids` string[] — Filter to specific Items. Multiple values are OR'd. Combined with other filters using AND.
  - `delivery_statuses` WebhookEventDeliveryStatus[] — Filter by delivery status. Returns webhook events whose latest delivery state matches any of the supplied values. Combined with other filters using AND.

## Response `200`

OK

- BetaWebhookEventsListResponse — BetaWebhookEventsListResponse defines the response schema for `/beta/webhook_events/list`
  - `webhook_events` WebhookEvent[], required — Webhook events sent to the calling client.
    - `webhook_message_id` string, required — Stable, opaque, per-webhook ID for deduplication and support reference.
    - `webhook_type` string, required — The webhook type.
    - `webhook_code` string, required — The webhook code.
    - `item_id` string, nullable, required — The Item ID associated with the webhook, if any.
    - `sent_time` string, date-time, required — The time Plaid sent the webhook.
    - `payload` WebhookEventPayload, required — The JSON body Plaid sent to the webhook destination.
    - `destination_url` string, required — The destination URL Plaid sent the webhook to.
    - `delivery_status` 'PENDING' | 'DELIVERED' | 'FAILED', required — Latest delivery state for this webhook. `PENDING`: Plaid has not yet received a successful response and may still retry. `DELIVERED`: the destination returned a 2xx response. `FAILED`: all delivery attempts were exhausted without a 2xx response.
    - `last_http_status_code` integer, nullable, required — The most recent HTTP status code returned by the destination, if any.
    - `attempt_count` integer, required — Number of delivery attempts Plaid has made for this webhook.
    - `last_attempt_time` string, date-time, nullable, required — The most recent delivery attempt timestamp. Null if Plaid has not yet attempted delivery.
  - `has_more` boolean, required — Indicates whether another page of webhook events is available.
  - `next_cursor` string, 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_id` string, required — A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

## Other responses

- `default` — Error response

---

[API](https://skmtc.net/plaid/apis/the-plaid-api.md) · [All operations](https://skmtc.net/plaid/apis/the-plaid-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/plaid/the-plaid-api/revisions/e536704a333f/schema)