Skip to main content
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"
}
FieldTypeDescription
idstringUnique event identifier (UUID). Remains the same across retry attempts, so consumers can idempotently handle duplicate events. Test events use the prefix evt_test_.
typestringThe event type string (e.g., ping, direct_transfer.deposit.confirmed).
timestampstringRFC 3339 UTC timestamp of the webhook delivery creation (e.g., 2026-04-10T18:32:24.000Z).
versionstringAPI version. Currently v2.
Direct transfer deposit events also include these shared fields:
FieldTypeDescription
chain_namestringHuman-readable chain name (e.g., Ethereum Sepolia).
chain_idstringEVM chain ID as a string (e.g., 11155111).
organization_idstringUUID of the receiving organization.
direct_transfer_addressstringThe Direct Transfer Address that received the stablecoins.
user_destination_addressstringThe end-user address receiving vault shares.
distributor_code_depositor_addressstringThe Distributor Code Depositor contract address.
vault_addressstringThe vault contract address.
input_token_symbolstringToken symbol (e.g., USDC).
input_token_addressstringERC-20 token contract address.
input_token_decimalsnumberToken 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

FieldTypeDescription
received_amountstringAmount received in the token’s smallest unit. String for bigint serialization.
receipt_tx_hashstringTransaction hash of the deposit into the Direct Transfer Address.
receipt_log_indexstringLog index of the deposit transaction.
receipt_tx_block_hashstringBlock 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

FieldTypeDescription
received_amountstringAmount received in the token’s smallest unit.
minted_amountstringValue of shares minted to the user, denominated in the input token’s smallest unit.
forward_tx_hashstringTransaction hash from forwarding funds from the DTA into the DCD.
forward_log_indexstringLog index of the forward transaction.
forward_tx_block_hashstringBlock 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

FieldTypeDescription
received_amountstringAmount received in the token’s smallest unit.
forward_tx_hashstring | nullTransaction hash of the forward attempt. null if the transaction was never sent.
forward_log_indexstring | nullLog index of the forward attempt. null if the transaction was never sent.
forward_tx_block_hashstring | nullBlock hash of the forward attempt. null if the transaction was never sent.
errorstringHuman-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.