> ## 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.
# Event Catalog
> Complete reference of all webhook event types, payload schemas, and example payloads
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:
```json theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"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:
```js theme={null}
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:
```js theme={null}
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.