Webhook events

Recover webhooks your endpoint missed

=*=*=*=

/beta/webhook_events/list returns webhook events for your account from the last 7 days, regardless of delivery outcome. Results are ordered by sent_time, oldest first, and paginated with a cursor so you can recover deliveries your endpoint missed. Each event includes a webhook_message_id that stays the same if that event shows up again on a later poll, so you can skip events you have already handled.

TRANSACTIONS webhooks are not returned. Use /transactions/sync to recover transaction updates.

Filtering is optional. For webhook_types, webhook_codes, item_ids, and delivery_statuses, values within a field match with OR; different fields combine with AND. For example, webhook_types: ["ITEM", "AUTH"] matches events of either type.

To page through events:

On the first request, omit cursor. You can set start_time to a time within the last 7 days, or omit start_time to start at the oldest retained event.
On later requests, send the previous response's next_cursor as cursor. If you also send start_time, it is ignored; cursor takes precedence, even when start_time has changed.
Save next_cursor even when has_more is false, and send that cursor on the next poll so you only receive events newer than the ones you have already seen.

A request fails with 400 in these cases:

WEBHOOK_EVENTS_START_TIME_OUT_OF_RANGE (INVALID_INPUT) is returned when cursor is omitted and start_time is earlier than the 7-day retention window. Retry with a start_time within the last 7 days, or omit start_time.
WEBHOOK_EVENTS_CURSOR_EXPIRED (INVALID_INPUT) is returned when the cursor is older than the 7-day retention window and can no longer be resolved. Start again with a start_time within the last 7 days. Events older than that window are no longer available.
INVALID_FIELD (INVALID_REQUEST) is returned when cursor is not a properly formatted string, or when the request is otherwise invalid.

This endpoint is in beta and may change in backwards-incompatible ways before it is generally available. Send feedback or bug reports to building@plaid.com.

/beta/webhook_events/list

Request fields

client_id

stringstring

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

stringstring

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

stringstring

Opaque cursor from a prior /beta/webhook_events/list response next_cursor. Use this on subsequent requests to continue forward. If start_time is also provided, it is ignored; cursor takes precedence.

Max length: 512

start_time

stringstring

ISO-8601 timestamp. Returns webhook events with sent_time greater than or equal to this value. When cursor is provided, this value is ignored, even if it has changed or falls outside the 7-day retention window. Otherwise, it must not be earlier than the 7-day retention window. Omit both cursor and start_time to begin from the oldest retained event.

Format: date-time

count

integerinteger

Page size. Default 100, maximum 100.

Minimum: 1

Maximum: 100

Default: 100

webhook_types

[string][string]

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_codes

[string][string]

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_ids

[string][string]

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_statuses

[string][string]

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

Possible values: PENDING, DELIVERED, FAILED

/beta/webhook_events/list

// 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);
}

/beta/webhook_events/list

Response fields

webhook_events

[object][object]

Webhook events for your account.

webhook_message_id

stringstring

Stable, opaque ID for this webhook event. The same value is returned if the event appears again on a later poll. Quote it when contacting support.

webhook_type

stringstring

The webhook type.

webhook_code

stringstring

The webhook code.

item_id

nullablestringnullable, string

The Item ID associated with the webhook, if any.

sent_time

stringstring

The time Plaid sent the webhook.

Format: date-time

payload

objectobject

The JSON body Plaid sent to the webhook destination.

destination_url

stringstring

The destination URL Plaid sent the webhook to.

delivery_status

stringstring

Latest delivery state for this webhook.

PENDING: Plaid has not recorded a successful response and may still retry. Treat PENDING as unknown rather than undelivered: a delivery may have succeeded without the outcome being recorded.

DELIVERED: the destination returned a 2xx response.

FAILED: all delivery attempts were exhausted without a 2xx response.

Possible values: PENDING, DELIVERED, FAILED

last_http_status_code

nullableintegernullable, integer

The most recent HTTP status code returned by the destination, if any.

attempt_count

integerinteger

Number of delivery attempts Plaid has made for this webhook.

last_attempt_time

nullablestringnullable, string

The most recent delivery attempt timestamp. Null if Plaid has not yet attempted delivery.

Format: date-time

has_more

booleanboolean

Indicates whether another page of webhook events is available.

next_cursor

stringstring

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

stringstring

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

Response Object

{
  "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"
}

Webhook events

Recover webhooks your endpoint missed

`/beta/webhook_events/list`

List webhook events