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: ["ITEM", "AUTH"] 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. Sending both returns INVALID_FIELD.
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.

Errors:

WEBHOOK_EVENTS_START_TIME_OUT_OF_RANGE (400) is returned when start_time is earlier than the 7-day retention window. Retry with a start_time within the last 7 days, or omit it.

WEBHOOK_EVENTS_CURSOR_EXPIRED (400) is returned when the cursor's position is older than the 7-day retention window and can no longer be resolved. Restart pagination with a start_time within the last 7 days.

INVALID_FIELD (400) is returned when cursor is not a properly formatted string, when both cursor and start_time are provided, or when the request is otherwise invalid.

{
  "webhook_types": [
    "ITEM",
    "AUTH"
  ],
  "webhook_codes": [
    "ERROR"
  ],
  "item_ids": [
    "abc123"
  ]
}