Event Catalog

This page documents every webhook event type available in Paxos Labs. All events use a flat JSON structure with shared common fields and type-specific fields at the top level.

Common Fields

Every webhook event includes these fields:

{
  "id": "1234567890",
  "type": "direct_transfer.deposit.confirmed",
  "timestamp": "2026-04-10T18:32:24.000Z",
  "version": "v2"
}

Field	Type	Description
`id`	`string`	Unique event identifier (UUID). Remains the same across retry attempts, so consumers can idempotently handle duplicate events. Test events use the prefix `evt_test_`.
`type`	`string`	The event type string (e.g., `ping`, `direct_transfer.deposit.confirmed`).
`timestamp`	`string`	RFC 3339 UTC timestamp of the webhook delivery creation (e.g., `2026-04-10T18:32:24.000Z`).
`version`	`string`	API version. Currently `v2`.

Direct transfer deposit events also include these shared fields:

Field	Type	Description
`chain_name`	`string`	Human-readable chain name (e.g., `Ethereum Sepolia`).
`chain_id`	`string`	EVM chain ID as a string (e.g., `11155111`).
`organization_id`	`string`	UUID of the receiving organization.
`direct_transfer_address`	`string`	The Direct Transfer Address that received the stablecoins.
`user_destination_address`	`string`	The end-user address receiving vault shares.
`distributor_code_depositor_address`	`string`	The Distributor Code Depositor contract address.
`vault_address`	`string`	The vault contract address.
`input_token_symbol`	`string`	Token symbol (e.g., `USDC`).
`input_token_address`	`string`	ERC-20 token contract address.
`input_token_decimals`	`number`	Token decimal places (e.g., `6` for USDC).

Event Types

`ping`

A lightweight connectivity test. Sent when you click Send Test in the Paxos Labs Console with no specific event type selected.

{
  "id": "1234567890",
  "type": "ping",
  "timestamp": "2026-04-10T18:32:24.000Z",
  "version": "v2"
}

The ping event contains only the common fields — no additional fields.

`direct_transfer.deposit.pending`

Paxos Labs has received the stablecoins and initiated the process to deposit them into the vault.

{
  "id": "1234567890",
  "type": "direct_transfer.deposit.pending",
  "timestamp": "2026-04-10T18:32:24.000Z",
  "version": "v2",
  "chain_name": "Ethereum Sepolia",
  "chain_id": "11155111",
  "organization_id": "700768ae-c71d-42cc-9ff9-13b777d6d379",
  "direct_transfer_address": "0xdta0000000000000000000000000000000123",
  "user_destination_address": "0xuda0000000000000000000000000000000000456",
  "distributor_code_depositor_address": "0xdcd0000000000000000000000000000000123",
  "vault_address": "0xvlt0000000000000000000000000000000999",
  "input_token_symbol": "USDC",
  "input_token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  "input_token_decimals": 6,
  "received_amount": "10000000",
  "receipt_tx_hash": "0x1234",
  "receipt_log_index": "25",
  "receipt_tx_block_hash": "0x4567"
}

Event-Specific Fields

Field	Type	Description
`received_amount`	`string`	Amount received in the token’s smallest unit. String for bigint serialization.
`receipt_tx_hash`	`string`	Transaction hash of the deposit into the Direct Transfer Address.
`receipt_log_index`	`string`	Log index of the deposit transaction.
`receipt_tx_block_hash`	`string`	Block hash of the deposit transaction.

`direct_transfer.deposit.confirmed`

Stablecoins have been successfully deposited into the vault and shares have been minted to the destination address.

{
  "id": "1234567890",
  "type": "direct_transfer.deposit.confirmed",
  "timestamp": "2026-04-10T18:32:24.000Z",
  "version": "v2",
  "chain_name": "Ethereum Sepolia",
  "chain_id": "11155111",
  "organization_id": "700768ae-c71d-42cc-9ff9-13b777d6d379",
  "direct_transfer_address": "0xdta0000000000000000000000000000000123",
  "user_destination_address": "0xuda0000000000000000000000000000000000456",
  "distributor_code_depositor_address": "0xdcd0000000000000000000000000000000123",
  "vault_address": "0xvlt0000000000000000000000000000000999",
  "input_token_symbol": "USDC",
  "input_token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  "input_token_decimals": 6,
  "received_amount": "10000000",
  "minted_amount": "9000000",
  "forward_tx_hash": "0x1234",
  "forward_log_index": "25",
  "forward_tx_block_hash": "0x4567"
}

Event-Specific Fields

Field	Type	Description
`received_amount`	`string`	Amount received in the token’s smallest unit.
`minted_amount`	`string`	Value of shares minted to the user, denominated in the input token’s smallest unit.
`forward_tx_hash`	`string`	Transaction hash from forwarding funds from the DTA into the DCD.
`forward_log_index`	`string`	Log index of the forward transaction.
`forward_tx_block_hash`	`string`	Block hash of the forward transaction.

`direct_transfer.deposit.failed`

Unable to deposit stablecoins. Funds remain at the Direct Transfer Address. The customer must be notified.

{
  "id": "1234567890",
  "type": "direct_transfer.deposit.failed",
  "timestamp": "2026-04-10T18:32:24.000Z",
  "version": "v2",
  "chain_name": "Ethereum Sepolia",
  "chain_id": "11155111",
  "organization_id": "700768ae-c71d-42cc-9ff9-13b777d6d379",
  "direct_transfer_address": "0xdta0000000000000000000000000000000123",
  "user_destination_address": "0xuda0000000000000000000000000000000000456",
  "distributor_code_depositor_address": "0xdcd0000000000000000000000000000000123",
  "vault_address": "0xvlt0000000000000000000000000000000999",
  "input_token_symbol": "USDC",
  "input_token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  "input_token_decimals": 6,
  "received_amount": "10000000",
  "forward_tx_hash": null,
  "forward_log_index": null,
  "forward_tx_block_hash": null,
  "error": "Vault cap reached"
}

Event-Specific Fields

Field	Type	Description
`received_amount`	`string`	Amount received in the token’s smallest unit.
`forward_tx_hash`	`string \| null`	Transaction hash of the forward attempt. `null` if the transaction was never sent.
`forward_log_index`	`string \| null`	Log index of the forward attempt. `null` if the transaction was never sent.
`forward_tx_block_hash`	`string \| null`	Block hash of the forward attempt. `null` if the transaction was never sent.
`error`	`string`	Human-readable error describing why the deposit failed (e.g., vault cap reached, predicate failure, out of gas).

When you receive a direct_transfer.deposit.failed event, stablecoins remain at the Direct Transfer Address. You should notify the end user and coordinate resolution.

Common Patterns

Idempotent Processing

Events may be delivered more than once. Use the id field to deduplicate:

const processedEvents = new Set()

function handleWebhook(event) {
  if (processedEvents.has(event.id)) {
    return  // already processed
  }
  processedEvents.add(event.id)

  switch (event.type) {
    case 'direct_transfer.deposit.confirmed':
      creditUserAccount(event)
      break
    case 'direct_transfer.deposit.failed':
      notifyUserOfFailure(event)
      break
  }
}

In production, store processed event IDs in a database rather than in-memory to survive restarts.

Type-Based Routing

Route events to different handlers based on the type field:

const handlers = {
  'ping':                                () => console.log('pong'),
  'direct_transfer.deposit.pending':     (evt) => trackPendingDeposit(evt),
  'direct_transfer.deposit.confirmed':   (evt) => finalizeDeposit(evt.organization_id, evt.minted_amount),
  'direct_transfer.deposit.failed':      (evt) => handleFailure(evt.organization_id, evt.error),
}

function handleWebhook(event) {
  const handler = handlers[event.type]
  if (handler) {
    handler(event)
  } else {
    console.warn(`Unhandled event type: ${event.type}`)
  }
}

Testing with the Paxos Labs Console

The Paxos Labs Console lets you send test events for any subscribed event type. Test events:

Have IDs prefixed with evt_test_
Contain representative sample data (not real transactions)
Are labeled Test in delivery history

Use test events to verify your endpoint connectivity and signature verification before going live.

Getting started

Origin - Branded Stablecoins

Amplify - Stablecoin Earn

Webhooks

Access - Borrow

USDG0

Common Fields

Event Types

`ping`

`direct_transfer.deposit.pending`

Event-Specific Fields

`direct_transfer.deposit.confirmed`

Event-Specific Fields

`direct_transfer.deposit.failed`

Event-Specific Fields

Common Patterns

Idempotent Processing

Type-Based Routing

Testing with the Paxos Labs Console

​Common Fields

​Event Types

​ping

​direct_transfer.deposit.pending

​Event-Specific Fields

​direct_transfer.deposit.confirmed

​Event-Specific Fields

​direct_transfer.deposit.failed

​Event-Specific Fields

​Common Patterns

​Idempotent Processing

​Type-Based Routing

​Testing with the Paxos Labs Console

Common Fields

Event Types

`ping`

`direct_transfer.deposit.pending`

Event-Specific Fields

`direct_transfer.deposit.confirmed`

Event-Specific Fields

`direct_transfer.deposit.failed`

Event-Specific Fields

Common Patterns

Idempotent Processing

Type-Based Routing

Testing with the Paxos Labs Console