Webhooks

A webhook record stores the raw payload of every Plaid webhook event received for a user’s item, along with metadata about the mining operation that resulted from it. This provides a full audit trail of Plaid-initiated events.

Webhooks arrive at the prod-txn-webhook Lambda via the prod-floatme-webhook-api API Gateway. After verification, they are enqueued onto the prod-txn-plaid-webhooks SQS queue and processed by the prod-txn-miner Lambda. The miner writes the webhook record to DynamoDB before processing.

See Plaid Mining Pipeline for the full processing flow.

Storage

Table: prod-txn-transactions

Region: us-east-2

Keys

Key Value

PK

WEBHOOK_ITEM#<item_id>

SK

DATETIME#<datetime>#TYPE#<type>#CODE#<code>

GSI1PK

WEBHOOK_USER#<user_id>

GSI1SK

DATETIME#<datetime>#TYPE#<type>#CODE#<code>#WEBHOOK_ITEM#<item_id>

GSI2PK

WEBHOOK_ITEM#<item_id>

GSI2SK

TYPE#<type>#CODE#<code>#DATETIME#<datetime>

GSI3PK

WEBHOOK_USER#<user_id>

GSI3SK

TYPE#<type>#CODE#<code>#DATETIME#<datetime>#WEBHOOK_ITEM#<item_id>

GSI4PK

WEBHOOK_ITEM#<item_id>

GSI4SK

SOURCE#<source>#TYPE#<type>#CODE#<code>#DATETIME#<datetime>

Attributes

Attribute Description

type

Always WEBHOOK_INFO

user_id

FloatMe user identifier

item_id

Plaid item identifier the webhook relates to

source

Origin of the webhook event. See Webhook Sources.

created_on

RFC3339 timestamp when this webhook record was stored

webhook

Raw Plaid webhook payload. See Webhook Payload.

update_info

Summary of the mining operation triggered by this webhook. See Update Info.

Webhook Payload

The webhook field contains the original Plaid webhook body:

Field Description

webhook_type

Plaid webhook type (e.g., TRANSACTIONS, ITEM, AUTH, LIABILITIES, IDENTITY_VERIFICATION)

webhook_code

Plaid webhook code (e.g., DEFAULT_UPDATE, INITIAL_UPDATE, LOGIN_REPAIRED, ERROR)

new_transactions

For TRANSACTIONS webhooks: number of new transactions available

removed_transactions

For TRANSACTIONS_REMOVED webhooks: array of Plaid transaction IDs that were removed

Update Info

The update_info field is populated by the miner with a summary of the data retrieved from Plaid during processing:

Field Description

total_transactions

Total number of transactions available in Plaid for the requested date range

plaid_accounts

Array of accounts retrieved from Plaid. Each entry contains account_id, type, and name.

institution_id

Plaid institution identifier

Webhook Sources

The source field identifies how the webhook was generated:

Source Description

(empty)

Standard webhook sent directly from Plaid

FROM_LISTENER

Synthetic webhook generated by the listener Lambda in response to an Auth0 login event

Query Patterns

Query Index Conditions

List webhooks for an item (by time, newest first)

Primary

PK = WEBHOOK_ITEM#<item_id>, SK begins_with DATETIME#

List webhooks for a user (by time, newest first)

GSI1

GSI1PK = WEBHOOK_USER#<user_id>, GSI1SK begins_with DATETIME#

List webhooks for an item filtered by type

GSI2

GSI2PK = WEBHOOK_ITEM#<item_id>, GSI2SK begins_with TYPE#<type>

List webhooks for an item filtered by type and code

GSI2

GSI2PK = WEBHOOK_ITEM#<item_id>, GSI2SK begins_with TYPE#<type>#CODE#<code>

List webhooks for a user filtered by type

GSI3

GSI3PK = WEBHOOK_USER#<user_id>, GSI3SK begins_with TYPE#<type>

List webhooks for a user filtered by type and code

GSI3

GSI3PK = WEBHOOK_USER#<user_id>, GSI3SK begins_with TYPE#<type>#CODE#<code>
GSI4 is used internally by the listener Lambda to look up webhooks by source (e.g., find all FROM_LISTENER synthetic webhooks for an item). It is not exposed via the API.

Related Pages