Documentation Index
Fetch the complete documentation index at: https://developers.paxoslabs.com/llms.txt
Use this file to discover all available pages before exploring further.
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. |
| 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"
}
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.
