Webhooks - XentFi API Documentation

Overview

Why Use Webhooks?

⚡ Real-time Updates

Receive notifications instantly when events happen

🔄 Automatic Retries

Failed deliveries are automatically retried

🔒 Secure Verification

Every webhook includes a signature to verify authenticity

📊 Event Logging

Complete history of all webhook deliveries

🎯 Selective Events

Subscribe only to the events you care about

🚀 Scalable

Handle high-volume event streams

Event Types

Wildcard Subscriptions

Pattern	Matches
`*`	All events
`address.*`	All address events
`master.*`	All master wallet events
`payment_link.*`	All payment link events
`payment_link_transfer.*`	All payment link transfer events
`address_settlement_rule.*`	All address settlement rule events
`master_settlement_rule.*`	All master settlement rule events

Address Events

Event	Trigger	Description
`address.incoming_transfer`	Incoming transfer detected	Address received funds
`address.created`	New address created	Deposit address generated
`address.updated`	Address updated	Address configuration changed
`address.swap_executed`	Swap completed	Token swap executed successfully
`address.swap_failed`	Swap failed	Token swap execution failed
`address.transfer_executed`	Transfer completed	Transfer executed successfully
`address.transfer_failed`	Transfer failed	Transfer execution failed
`address.signed_success`	Signing successful	Transaction/message signed successfully
`address.signed_failed`	Signing failed	Signing operation failed

Master Wallet Events

Event	Trigger	Description
`master.incoming_transfer`	Incoming transfer detected	Master wallet received funds
`master.created`	New wallet created	Master wallet generated
`master.updated`	Wallet updated	Master wallet configuration changed
`master.swap_executed`	Swap completed	Master wallet swap executed successfully
`master.swap_failed`	Swap failed	Master wallet swap execution failed
`master.transfer_executed`	Transfer completed	Master wallet transfer executed successfully
`master.transfer_failed`	Transfer failed	Master wallet transfer execution failed
`master.signed_success`	Signing successful	Master wallet transaction/message signed successfully
`master.signed_failed`	Signing failed	Master wallet signing operation failed

Payment Link Events

Event	Trigger	Description
`payment_link.created`	Link generated	New payment link created
`payment_link.updated`	Link updated	Payment link configuration changed
`payment_link.deleted`	Link deleted	Payment link removed

Payment Link Transfer Events

Event	Trigger	Description
`payment_link_deposit.success`	Deposit successful	Payment link deposit completed
`payment_link_deposit.failed`	Deposit failed	Payment link deposit failed

Address Settlement Rule Events

Event	Trigger	Description
`address_settlement_rule.created`	Rule created	Address settlement rule created
`address_settlement_rule.updated`	Rule updated	Address settlement rule updated
`address_settlement_rule.deleted`	Rule deleted	Address settlement rule removed
`address_settlement_rule.executed`	Rule executed	Address settlement rule executed successfully
`address_settlement_rule.failed`	Rule failed	Address settlement rule execution failed

Master Settlement Rule Events

Event	Trigger	Description
`master_settlement_rule.created`	Rule created	Master settlement rule created
`master_settlement_rule.updated`	Rule updated	Master settlement rule updated
`master_settlement_rule.deleted`	Rule deleted	Master settlement rule removed
`master_settlement_rule.executed`	Rule executed	Master settlement rule executed successfully
`master_settlement_rule.failed`	Rule failed	Master settlement rule execution failed

Here is the complete and comprehensive MDX section for Webhook Payloads with all event types and their corresponding mock payloads:

Webhook Payloads

All webhook payloads follow a consistent structure with common fields:

id: Unique event identifier
type: The event type (matches the EventTypes enum)
version: API version
timestamp: ISO 8601 timestamp of when the event occurred
data: The event-specific payload

Event Type: address.incoming_transferTriggered when a transfer is detected on an address (child wallet).

{
    "id": "evt_123e4567-e89b-12d3-a456-426614174000",
    "type": "address.incoming_transfer",
    "version": "1.0",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "data": {
        "hash": "0x28a1bfa727a024dd450352e736f957ac6f08471825362130ef1c3b4da536ebfb",
        "blockNumber": "18500000",
        "from": "0xSenderAddress...",
        "to": "0xRecipientAddress...",
        "value": "100.50",
        "asset": {
            "id": "69d851b9-c358-4359-becd-3e614ca1ab4d",
            "symbol": "EURC",
            "decimals": 6
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base",
            "slug": "base-mainnet"
        },
        "wallet": {
            "id": "addr_123e4567",
            "name": "Customer Deposit Address",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
            "masterWalletId": "master_123e4567"
        },
        "rawContract": {
            "address": "0x08210F9170F89Ab7658F0B5E3fF39b0E03C594D4",
            "decimals": 6,
            "rawValue": "100500000"
        }
    }
}

Event Type: address.createdTriggered when a new address (child wallet) is created.

{
    "id": "evt_123e4567-e89b-12d3-a456-426614174001",
    "type": "address.created",
    "version": "1.0",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "data": {
        "wallet": {
            "id": "addr_123e4567",
            "name": "Customer Deposit Address",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
            "masterWalletId": "master_123e4567",
            "type": "INTERNAL",
            "isActive": true,
            "configurations": {
                "disableAutoSweep": false,
                "enableGaslessWithdraw": true,
                "enableMultiChain": true
            }
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base",
            "slug": "base-mainnet"
        },
        "metadata": {
            "source": "dashboard",
            "createdBy": "user_123"
        }
    }
}

Event Type: address.updatedTriggered when an address configuration is updated.

{
    "id": "evt_123e4567-e89b-12d3-a456-426614174002",
    "type": "address.updated",
    "version": "1.0",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "data": {
        "wallet": {
            "id": "addr_123e4567",
            "name": "Customer Deposit Address - Updated",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
            "masterWalletId": "master_123e4567",
            "isActive": true
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base",
            "slug": "base-mainnet"
        },
        "changes": {
            "name": {
                "old": "Customer Deposit Address",
                "new": "Customer Deposit Address - Updated"
            },
            "configurations.settlement.autoSettlementEnabled": {
                "old": false,
                "new": true
            }
        },
        "metadata": {
            "updatedBy": "user_123"
        }
    }
}

Event Type: address.swap_executedTriggered when a swap is executed successfully on an address.

{
    "id": "evt_123e4567-e89b-12d3-a456-426614174003",
    "type": "address.swap_executed",
    "version": "1.0",
    "timestamp": "2024-01-15T10:35:00.000Z",
    "data": {
        "status": "SUCCESS",
        "txhash": "0x28a1bfa727a024dd450352e736f957ac6f08471825362130ef1c3b4da536ebfb",
        "explorerUrl": "https://etherscan.io/tx/0x28a1bfa727a024dd450352e736f957ac6f08471825362130ef1c3b4da536ebfb",
        "srcWalet": {
            "id": "addr_123e4567",
            "name": "Customer Deposit Address",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "dstAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0b5b5",
        "srcAsset": {
            "id": "asset_eth_123",
            "symbol": "ETH",
            "decimals": 18
        },
        "dstAsset": {
            "id": "asset_usdc_456",
            "symbol": "USDC",
            "decimals": 6
        },
        "inputAmount": 1.5,
        "outputAmount": 3450.5,
        "minOutputAmount": 3430.25,
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base"
        },
        "gasFee": {
            "amount": "0.00021",
            "token": "ETH",
            "chainId": 8453
        }
    }
}

Event Type: address.swap_failedTriggered when a swap fails on an address.

{
    "id": "evt_123e4567-e89b-12d3-a456-426614174004",
    "type": "address.swap_failed",
    "version": "1.0",
    "timestamp": "2024-01-15T10:35:00.000Z",
    "data": {
        "status": "FAILED",
        "txhash": null,
        "explorerUrl": null,
        "srcWalet": {
            "id": "addr_123e4567",
            "name": "Customer Deposit Address",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "dstAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0b5b5",
        "srcAsset": {
            "id": "asset_eth_123",
            "symbol": "ETH",
            "decimals": 18
        },
        "dstAsset": {
            "id": "asset_usdc_456",
            "symbol": "USDC",
            "decimals": 6
        },
        "inputAmount": 1.5,
        "outputAmount": 0,
        "minOutputAmount": 3430.25,
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base"
        },
        "error": "Insufficient liquidity for swap"
    }
}

Event Type: address.transfer_executedTriggered when a transfer is executed successfully from an address.

{
    "id": "evt_123e4567-e89b-12d3-a456-426614174005",
    "type": "address.transfer_executed",
    "version": "1.0",
    "timestamp": "2024-01-15T10:35:00.000Z",
    "data": {
        "status": "SUCCESS",
        "txhash": "0x28a1bfa727a024dd450352e736f957ac6f08471825362130ef1c3b4da536ebfb",
        "explorerUrl": "https://etherscan.io/tx/0x28a1bfa727a024dd450352e736f957ac6f08471825362130ef1c3b4da536ebfb",
        "fromAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
        "toAddress": "0xRecipientAddress...",
        "amount": "100.50",
        "asset": {
            "id": "69d851b9-c358-4359-becd-3e614ca1ab4d",
            "symbol": "EURC",
            "decimals": 6
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base"
        },
        "wallet": {
            "id": "addr_123e4567",
            "name": "Customer Deposit Address",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        }
    }
}

Event Type: address.transfer_failedTriggered when a transfer fails from an address.

{
    "id": "evt_123e4567-e89b-12d3-a456-426614174006",
    "type": "address.transfer_failed",
    "version": "1.0",
    "timestamp": "2024-01-15T10:35:00.000Z",
    "data": {
        "status": "FAILED",
        "txhash": null,
        "explorerUrl": null,
        "fromAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
        "toAddress": "0xRecipientAddress...",
        "amount": "100.50",
        "asset": {
            "id": "69d851b9-c358-4359-becd-3e614ca1ab4d",
            "symbol": "EURC",
            "decimals": 6
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base"
        },
        "wallet": {
            "id": "addr_123e4567",
            "name": "Customer Deposit Address",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "error": "Insufficient balance"
    }
}

Event Type: address.signed_successTriggered when a message is signed successfully by an address.

{
    "id": "evt_123e4567-e89b-12d3-a456-426614174007",
    "type": "address.signed_success",
    "version": "1.0",
    "timestamp": "2024-01-15T10:35:00.000Z",
    "data": {
        "status": "SUCCESS",
        "signature": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
        "message": "Sign this message to verify ownership",
        "wallet": {
            "id": "addr_123e4567",
            "name": "Customer Deposit Address",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base"
        }
    }
}

Event Type: address.signed_failedTriggered when message signing fails on an address.

{
    "id": "evt_123e4567-e89b-12d3-a456-426614174008",
    "type": "address.signed_failed",
    "version": "1.0",
    "timestamp": "2024-01-15T10:35:00.000Z",
    "data": {
        "status": "FAILED",
        "signature": null,
        "message": "Sign this message to verify ownership",
        "wallet": {
            "id": "addr_123e4567",
            "name": "Customer Deposit Address",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base"
        },
        "error": "Invalid private key"
    }
}

Event Type: master.incoming_transferTriggered when a transfer is detected on a master wallet.

{
    "id": "evt_123e4567-e89b-12d3-a456-426614174009",
    "type": "master.incoming_transfer",
    "version": "1.0",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "data": {
        "hash": "0x28a1bfa727a024dd450352e736f957ac6f08471825362130ef1c3b4da536ebfb",
        "blockNumber": "18500000",
        "from": "0xSenderAddress...",
        "to": "0xRecipientAddress...",
        "value": "1000.00",
        "asset": {
            "id": "69d851b9-c358-4359-becd-3e614ca1ab4d",
            "symbol": "EURC",
            "decimals": 6
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base",
            "slug": "base-mainnet"
        },
        "wallet": {
            "id": "master_123e4567",
            "name": "Main Treasury",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "rawContract": {
            "address": "0x08210F9170F89Ab7658F0B5E3fF39b0E03C594D4",
            "decimals": 6,
            "rawValue": "1000000000"
        }
    }
}

Event Type: master.createdTriggered when a new master wallet is created.

{
    "id": "evt_123e4567-e89b-12d3-a456-426614174010",
    "type": "master.created",
    "version": "1.0",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "data": {
        "wallet": {
            "id": "master_123e4567",
            "name": "Main Treasury",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
            "isActive": true,
            "configurations": {
                "enableMultiChain": true,
                "enableGaslessWithdraw": true
            }
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base",
            "slug": "base-mainnet"
        },
        "metadata": {
            "source": "dashboard",
            "createdBy": "user_123"
        }
    }
}

Event Type: master.updatedTriggered when a master wallet configuration is updated.

{
    "id": "evt_123e4567-e89b-12d3-a456-426614174011",
    "type": "master.updated",
    "version": "1.0",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "data": {
        "wallet": {
            "id": "master_123e4567",
            "name": "Main Treasury - Updated",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
            "isActive": true
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base",
            "slug": "base-mainnet"
        },
        "changes": {
            "name": {
                "old": "Main Treasury",
                "new": "Main Treasury - Updated"
            },
            "configurations.autoSweep.enabled": {
                "old": false,
                "new": true
            }
        },
        "metadata": {
            "updatedBy": "user_123"
        }
    }
}

Event Type: master.swap_executedTriggered when a swap is executed successfully on a master wallet.

{
    "id": "evt_456e7890-e89b-12d3-a456-426614174012",
    "type": "master.swap_executed",
    "version": "1.0",
    "timestamp": "2024-01-15T10:35:00.000Z",
    "data": {
        "status": "SUCCESS",
        "txhash": "0x28a1bfa727a024dd450352e736f957ac6f08471825362130ef1c3b4da536ebfb",
        "explorerUrl": "https://etherscan.io/tx/0x28a1bfa727a024dd450352e736f957ac6f08471825362130ef1c3b4da536ebfb",
        "srcWalet": {
            "id": "master_123e4567",
            "name": "Main Treasury",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "dstAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0b5b5",
        "srcAsset": {
            "id": "asset_eth_123",
            "symbol": "ETH",
            "decimals": 18
        },
        "dstAsset": {
            "id": "asset_usdc_456",
            "symbol": "USDC",
            "decimals": 6
        },
        "inputAmount": 1.5,
        "outputAmount": 3450.5,
        "minOutputAmount": 3430.25,
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base"
        },
        "gasFee": "0.00021",
        "feeAsset": {
            "id": "asset_eth_123",
            "symbol": "ETH",
            "decimals": 18
        }
    }
}

Event Type: master.swap_failedTriggered when a swap fails on a master wallet.

{
    "id": "evt_456e7890-e89b-12d3-a456-426614174013",
    "type": "master.swap_failed",
    "version": "1.0",
    "timestamp": "2024-01-15T10:35:00.000Z",
    "data": {
        "status": "FAILED",
        "txhash": null,
        "explorerUrl": null,
        "srcWalet": {
            "id": "master_123e4567",
            "name": "Main Treasury",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "dstAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0b5b5",
        "srcAsset": {
            "id": "asset_eth_123",
            "symbol": "ETH",
            "decimals": 18
        },
        "dstAsset": {
            "id": "asset_usdc_456",
            "symbol": "USDC",
            "decimals": 6
        },
        "inputAmount": 1.5,
        "outputAmount": 0,
        "minOutputAmount": 3430.25,
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base"
        },
        "gasFee": "0.00021",
        "feeAsset": {
            "id": "asset_eth_123",
            "symbol": "ETH",
            "decimals": 18
        },
        "error": "Slippage tolerance exceeded"
    }
}

Event Type: master.transfer_executedTriggered when a transfer is executed successfully from a master wallet.

{
    "id": "evt_456e7890-e89b-12d3-a456-426614174014",
    "type": "master.transfer_executed",
    "version": "1.0",
    "timestamp": "2024-01-15T10:35:00.000Z",
    "data": {
        "status": "SUCCESS",
        "txhash": "0x28a1bfa727a024dd450352e736f957ac6f08471825362130ef1c3b4da536ebfb",
        "explorerUrl": "https://etherscan.io/tx/0x28a1bfa727a024dd450352e736f957ac6f08471825362130ef1c3b4da536ebfb",
        "fromAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
        "toAddress": "0xRecipientAddress...",
        "amount": "1000.00",
        "asset": {
            "id": "69d851b9-c358-4359-becd-3e614ca1ab4d",
            "symbol": "EURC",
            "decimals": 6
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base"
        },
        "wallet": {
            "id": "master_123e4567",
            "name": "Main Treasury",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        }
    }
}

Event Type: master.transfer_failedTriggered when a transfer fails from a master wallet.

{
    "id": "evt_456e7890-e89b-12d3-a456-426614174015",
    "type": "master.transfer_failed",
    "version": "1.0",
    "timestamp": "2024-01-15T10:35:00.000Z",
    "data": {
        "status": "FAILED",
        "txhash": null,
        "explorerUrl": null,
        "fromAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
        "toAddress": "0xRecipientAddress...",
        "amount": "1000.00",
        "asset": {
            "id": "69d851b9-c358-4359-becd-3e614ca1ab4d",
            "symbol": "EURC",
            "decimals": 6
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base"
        },
        "wallet": {
            "id": "master_123e4567",
            "name": "Main Treasury",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "error": "Transaction rejected by security policy"
    }
}

Event Type: master.signed_successTriggered when a message is signed successfully by a master wallet.

{
    "id": "evt_456e7890-e89b-12d3-a456-426614174016",
    "type": "master.signed_success",
    "version": "1.0",
    "timestamp": "2024-01-15T10:35:00.000Z",
    "data": {
        "status": "SUCCESS",
        "signature": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
        "message": "Sign this message to verify ownership",
        "wallet": {
            "id": "master_123e4567",
            "name": "Main Treasury",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base"
        }
    }
}

Event Type: master.signed_failedTriggered when message signing fails on a master wallet.

{
    "id": "evt_456e7890-e89b-12d3-a456-426614174017",
    "type": "master.signed_failed",
    "version": "1.0",
    "timestamp": "2024-01-15T10:35:00.000Z",
    "data": {
        "status": "FAILED",
        "signature": null,
        "message": "Sign this message to verify ownership",
        "wallet": {
            "id": "master_123e4567",
            "name": "Main Treasury",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base"
        },
        "error": "Wallet not found"
    }
}

Event Type: payment_link.createdTriggered when a new payment link is created.

{
    "id": "evt_789e0123-e89b-12d3-a456-426614174018",
    "type": "payment_link.created",
    "version": "1.0",
    "timestamp": "2024-01-15T10:40:00.000Z",
    "data": {
        "paymentLinkId": "link_123e4567-e89b-12d3-a456-426614174000",
        "name": "Product Purchase",
        "slug": "product-purchase",
        "amount": "100.00",
        "currency": "USD",
        "redirectUrl": "https://yourapp.com/success",
        "isActive": true,
        "expiresAt": null,
        "paymentLimit": null,
        "paymentsConsumed": 0,
        "masterWallet": {
            "id": "master_123e4567",
            "name": "Main Treasury",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        }
    }
}

Event Type: payment_link.updatedTriggered when a payment link is updated.

{
    "id": "evt_789e0123-e89b-12d3-a456-426614174019",
    "type": "payment_link.updated",
    "version": "1.0",
    "timestamp": "2024-01-15T10:40:00.000Z",
    "data": {
        "paymentLinkId": "link_123e4567-e89b-12d3-a456-426614174000",
        "name": "Product Purchase - Updated",
        "slug": "product-purchase",
        "amount": "150.00",
        "currency": "USD",
        "redirectUrl": "https://yourapp.com/success",
        "isActive": true,
        "expiresAt": null,
        "paymentLimit": null,
        "paymentsConsumed": 0,
        "masterWallet": {
            "id": "master_123e4567",
            "name": "Main Treasury",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        }
    }
}

Event Type: payment_link.deletedTriggered when a payment link is deleted.

{
    "id": "evt_789e0123-e89b-12d3-a456-426614174020",
    "type": "payment_link.deleted",
    "version": "1.0",
    "timestamp": "2024-01-15T10:40:00.000Z",
    "data": {
        "paymentLinkId": "link_123e4567-e89b-12d3-a456-426614174000",
        "name": "Product Purchase",
        "slug": "product-purchase",
        "amount": "100.00",
        "currency": "USD",
        "redirectUrl": "https://yourapp.com/success",
        "isActive": false,
        "expiresAt": null,
        "paymentLimit": null,
        "paymentsConsumed": 0,
        "masterWallet": {
            "id": "master_123e4567",
            "name": "Main Treasury",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        }
    }
}

Event Type: payment_link_deposit.successTriggered when a payment link deposit is successful.

{
    "id": "evt_789e0123-e89b-12d3-a456-426614174021",
    "type": "payment_link_deposit.success",
    "version": "1.0",
    "timestamp": "2024-01-15T10:40:00.000Z",
    "data": {
        "id": "transfer_123e4567",
        "paymentLinkId": "link_123e4567-e89b-12d3-a456-426614174000",
        "reference": "pl_123e4567",
        "expectedAmount": "100.00",
        "paidAmount": "100.00",
        "remainingAmount": "0.00",
        "status": "COMPLETED",
        "asset": {
            "id": "69d851b9-c358-4359-becd-3e614ca1ab4d",
            "symbol": "EURC",
            "decimals": 6
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base"
        },
        "recipientAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
        "senderAddress": "0xSenderAddress...",
        "transactionHash": "0x28a1bfa727a024dd450352e736f957ac6f08471825362130ef1c3b4da536ebfb"
    }
}

Event Type: payment_link_deposit.failedTriggered when a payment link deposit fails.

{
    "id": "evt_789e0123-e89b-12d3-a456-426614174022",
    "type": "payment_link_deposit.failed",
    "version": "1.0",
    "timestamp": "2024-01-15T10:40:00.000Z",
    "data": {
        "id": "transfer_123e4567",
        "paymentLinkId": "link_123e4567-e89b-12d3-a456-426614174000",
        "reference": "pl_123e4567",
        "expectedAmount": "100.00",
        "paidAmount": "0.00",
        "remainingAmount": "100.00",
        "status": "FAILED",
        "asset": {
            "id": "69d851b9-c358-4359-becd-3e614ca1ab4d",
            "symbol": "EURC",
            "decimals": 6
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base"
        },
        "recipientAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
        "senderAddress": "0xSenderAddress...",
        "transactionHash": null,
        "error": "Payment amount does not match expected amount"
    }
}

Event Type: address_settlement_rule.createdTriggered when an address settlement rule is created.

{
    "id": "evt_234e5678-e89b-12d3-a456-426614174023",
    "type": "address_settlement_rule.created",
    "version": "1.0",
    "timestamp": "2024-01-15T10:45:00.000Z",
    "data": {
        "ruleId": "rule_123e4567",
        "ruleName": "Auto-Sweep to Treasury",
        "order": "FASTEST",
        "slippageTolerance": "0.5",
        "source": [
            {
                "assetId": "69d851b9-c358-4359-becd-3e614ca1ab4d",
                "minAmount": "10",
                "maxAmount": "1000"
            }
        ],
        "destination": {
            "assetId": "69d851b9-c358-4359-becd-3e614ca1ab4d",
            "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "wallet": {
            "id": "addr_123e4567",
            "name": "Customer Deposit Address",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base"
        }
    }
}

Event Type: address_settlement_rule.updatedTriggered when an address settlement rule is updated.

{
    "id": "evt_234e5678-e89b-12d3-a456-426614174024",
    "type": "address_settlement_rule.updated",
    "version": "1.0",
    "timestamp": "2024-01-15T10:45:00.000Z",
    "data": {
        "ruleId": "rule_123e4567",
        "ruleName": "Auto-Sweep to Treasury - Updated",
        "order": "CHEAPEST",
        "slippageTolerance": "1.0",
        "source": [
            {
                "assetId": "69d851b9-c358-4359-becd-3e614ca1ab4d",
                "minAmount": "5",
                "maxAmount": "2000"
            }
        ],
        "destination": {
            "assetId": "69d851b9-c358-4359-becd-3e614ca1ab4d",
            "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "wallet": {
            "id": "addr_123e4567",
            "name": "Customer Deposit Address",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base"
        }
    }
}

Event Type: address_settlement_rule.deletedTriggered when an address settlement rule is deleted.

{
    "id": "evt_234e5678-e89b-12d3-a456-426614174025",
    "type": "address_settlement_rule.deleted",
    "version": "1.0",
    "timestamp": "2024-01-15T10:45:00.000Z",
    "data": {
        "ruleId": "rule_123e4567",
        "ruleName": "Auto-Sweep to Treasury",
        "order": "FASTEST",
        "slippageTolerance": "0.5",
        "source": [
            {
                "assetId": "69d851b9-c358-4359-becd-3e614ca1ab4d",
                "minAmount": "10",
                "maxAmount": "1000"
            }
        ],
        "destination": {
            "assetId": "69d851b9-c358-4359-becd-3e614ca1ab4d",
            "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "wallet": {
            "id": "addr_123e4567",
            "name": "Customer Deposit Address",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base"
        }
    }
}

Event Type: address_settlement_rule.executedTriggered when an address settlement rule is executed successfully.

{
    "id": "evt_234e5678-e89b-12d3-a456-426614174026",
    "type": "address_settlement_rule.executed",
    "version": "1.0",
    "timestamp": "2024-01-15T10:45:00.000Z",
    "data": {
        "ruleId": "rule_123e4567",
        "ruleName": "Auto-Sweep to Treasury",
        "order": "FASTEST",
        "slippageTolerance": "0.5",
        "source": [
            {
                "assetId": "69d851b9-c358-4359-becd-3e614ca1ab4d",
                "minAmount": "10",
                "maxAmount": "1000"
            }
        ],
        "destination": {
            "assetId": "69d851b9-c358-4359-becd-3e614ca1ab4d",
            "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "wallet": {
            "id": "addr_123e4567",
            "name": "Customer Deposit Address",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base"
        },
        "txhash": "0x28a1bfa727a024dd450352e736f957ac6f08471825362130ef1c3b4da536ebfb",
        "amount": "100.00",
        "asset": {
            "id": "69d851b9-c358-4359-becd-3e614ca1ab4d",
            "symbol": "EURC",
            "decimals": 6
        }
    }
}

Event Type: address_settlement_rule.failedTriggered when an address settlement rule fails.

{
    "id": "evt_234e5678-e89b-12d3-a456-426614174027",
    "type": "address_settlement_rule.failed",
    "version": "1.0",
    "timestamp": "2024-01-15T10:45:00.000Z",
    "data": {
        "ruleId": "rule_123e4567",
        "ruleName": "Auto-Sweep to Treasury",
        "order": "FASTEST",
        "slippageTolerance": "0.5",
        "source": [
            {
                "assetId": "69d851b9-c358-4359-becd-3e614ca1ab4d",
                "minAmount": "10",
                "maxAmount": "1000"
            }
        ],
        "destination": {
            "assetId": "69d851b9-c358-4359-becd-3e614ca1ab4d",
            "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "wallet": {
            "id": "addr_123e4567",
            "name": "Customer Deposit Address",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base"
        },
        "error": "Insufficient balance for settlement"
    }
}

Event Type: master_settlement_rule.createdTriggered when a master settlement rule is created.

{
    "id": "evt_234e5678-e89b-12d3-a456-426614174028",
    "type": "master_settlement_rule.created",
    "version": "1.0",
    "timestamp": "2024-01-15T10:45:00.000Z",
    "data": {
        "ruleId": "rule_456e7890",
        "ruleName": "Master Treasury Sweep",
        "order": "FASTEST",
        "slippageTolerance": "0.5",
        "source": [
            {
                "assetId": "69d851b9-c358-4359-becd-3e614ca1ab4d",
                "minAmount": "100",
                "maxAmount": "10000"
            }
        ],
        "destination": {
            "assetId": "69d851b9-c358-4359-becd-3e614ca1ab4d",
            "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "wallet": {
            "id": "master_123e4567",
            "name": "Main Treasury",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base"
        }
    }
}

Event Type: master_settlement_rule.updatedTriggered when a master settlement rule is updated.

{
    "id": "evt_234e5678-e89b-12d3-a456-426614174029",
    "type": "master_settlement_rule.updated",
    "version": "1.0",
    "timestamp": "2024-01-15T10:45:00.000Z",
    "data": {
        "ruleId": "rule_456e7890",
        "ruleName": "Master Treasury Sweep - Updated",
        "order": "CHEAPEST",
        "slippageTolerance": "1.0",
        "source": [
            {
                "assetId": "69d851b9-c358-4359-becd-3e614ca1ab4d",
                "minAmount": "50",
                "maxAmount": "20000"
            }
        ],
        "destination": {
            "assetId": "69d851b9-c358-4359-becd-3e614ca1ab4d",
            "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "wallet": {
            "id": "master_123e4567",
            "name": "Main Treasury",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base"
        }
    }
}

Event Type: master_settlement_rule.deletedTriggered when a master settlement rule is deleted.

{
    "id": "evt_234e5678-e89b-12d3-a456-426614174030",
    "type": "master_settlement_rule.deleted",
    "version": "1.0",
    "timestamp": "2024-01-15T10:45:00.000Z",
    "data": {
        "ruleId": "rule_456e7890",
        "ruleName": "Master Treasury Sweep",
        "order": "FASTEST",
        "slippageTolerance": "0.5",
        "source": [
            {
                "assetId": "69d851b9-c358-4359-becd-3e614ca1ab4d",
                "minAmount": "100",
                "maxAmount": "10000"
            }
        ],
        "destination": {
            "assetId": "69d851b9-c358-4359-becd-3e614ca1ab4d",
            "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "wallet": {
            "id": "master_123e4567",
            "name": "Main Treasury",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base"
        }
    }
}

Event Type: master_settlement_rule.executedTriggered when a master settlement rule is executed successfully.

{
    "id": "evt_234e5678-e89b-12d3-a456-426614174031",
    "type": "master_settlement_rule.executed",
    "version": "1.0",
    "timestamp": "2024-01-15T10:45:00.000Z",
    "data": {
        "ruleId": "rule_456e7890",
        "ruleName": "Master Treasury Sweep",
        "order": "FASTEST",
        "slippageTolerance": "0.5",
        "source": [
            {
                "assetId": "69d851b9-c358-4359-becd-3e614ca1ab4d",
                "minAmount": "100",
                "maxAmount": "10000"
            }
        ],
        "destination": {
            "assetId": "69d851b9-c358-4359-becd-3e614ca1ab4d",
            "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "wallet": {
            "id": "master_123e4567",
            "name": "Main Treasury",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base"
        },
        "txhash": "0x28a1bfa727a024dd450352e736f957ac6f08471825362130ef1c3b4da536ebfb",
        "amount": "10000.00",
        "asset": {
            "id": "69d851b9-c358-4359-becd-3e614ca1ab4d",
            "symbol": "EURC",
            "decimals": 6
        }
    }
}

Event Type: master_settlement_rule.failedTriggered when a master settlement rule fails.

{
    "id": "evt_234e5678-e89b-12d3-a456-426614174032",
    "type": "master_settlement_rule.failed",
    "version": "1.0",
    "timestamp": "2024-01-15T10:45:00.000Z",
    "data": {
        "ruleId": "rule_456e7890",
        "ruleName": "Master Treasury Sweep",
        "order": "FASTEST",
        "slippageTolerance": "0.5",
        "source": [
            {
                "assetId": "69d851b9-c358-4359-becd-3e614ca1ab4d",
                "minAmount": "100",
                "maxAmount": "10000"
            }
        ],
        "destination": {
            "assetId": "69d851b9-c358-4359-becd-3e614ca1ab4d",
            "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "wallet": {
            "id": "master_123e4567",
            "name": "Main Treasury",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base"
        },
        "error": "Slippage tolerance exceeded"
    }
}

Webhook Headers

When delivering webhook events, XentFi includes important metadata in the HTTP headers. These headers help you verify the authenticity of the request and provide context about the event.

Request Headers

Header	Description	Example
`Content-Type`	Indicates the payload format	`application/json`
`X-Webhook-Signature`	HMAC-SHA256 signature for payload verification	`t=1705314600000,v1=abc123def456...`
`X-Event-ID`	Unique identifier for the webhook event	`evt_123e4567-e89b-12d3-a456-426614174000`
`X-Event-Type`	The type of event being delivered	`address.incoming_transfer`
`X-Timestamp`	ISO 8601 timestamp of when the delivery was initiated	`2024-01-15T10:30:00.000Z`
`X-Retry-Count`	Number of retry attempts for this event	`0`

Signature Format

The X-Webhook-Signature header follows this format:

t={timestamp},v1={signature}

Where:

t is the Unix timestamp in milliseconds
v1 is the HMAC-SHA256 signature using your webhook secret

Signature Verification Example

To verify the webhook signature, follow this process:

function verifyWebhookSignature(payload, signature, secret) {
  // Extract timestamp and signature from header
  const parts = signature.split(',');
  const timestampPart = parts.find(p => p.startsWith('t='));
  const signaturePart = parts.find(p => p.startsWith('v1='));

  if (!timestampPart || !signaturePart) {
    throw new Error('Invalid signature format');
  }

  const timestamp = parseInt(timestampPart.substring(2), 10);
  const receivedSignature = signaturePart.substring(3);

  // Create expected signature using the same method
  const payloadString = JSON.stringify(payload);
  const signaturePayload = `${timestamp}.${payloadString}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signaturePayload)
    .digest('hex');

  // Compare signatures (using timing-safe comparison)
  return crypto.timingSafeEqual(
    Buffer.from(receivedSignature),
    Buffer.from(expectedSignature)
  );
}

Important Security Notes

Always verify the webhook signature before processing any webhook event. This ensures the request came from XentFi and not from an imposter.

Check timestamp tolerance - Reject signatures with timestamps older than 5 minutes to prevent replay attacks
Use constant-time comparison - Use crypto.timingSafeEqual() to prevent timing attacks
Never trust unverified webhooks - Only process events after successful signature verification
Store secrets securely - Webhook secrets are sensitive credentials; never expose them in logs or client-side code

Example Webhook Delivery Request

Here’s a complete example of what a webhook delivery request looks like:

POST https://your-endpoint.com/webhooks/xentfi
Content-Type: application/json
X-Webhook-Signature: t=1705314600000,v1=1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t1u2v3w4x5y6z7a8b9c0d1e2f
X-Event-ID: evt_123e4567-e89b-12d3-a456-426614174000
X-Event-Type: address.incoming_transfer
X-Timestamp: 2024-01-15T10:30:00.000Z
X-Retry-Count: 0

{
  "id": "evt_123e4567-e89b-12d3-a456-426614174000",
  "type": "address.incoming_transfer",
  "version": "1.0",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "environment": "prod",
  "data": {
    "hash": "0x28a1bfa727a024dd450352e736f957ac6f08471825362130ef1c3b4da536ebfb",
    "blockNumber": "18500000",
    "from": "0xSenderAddress...",
    "to": "0xRecipientAddress...",
    "value": "100.50",
    "asset": {
      "id": "69d851b9-c358-4359-becd-3e614ca1ab4d",
      "symbol": "EURC",
      "decimals": 6
    },
    "blockchain": {
      "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
      "name": "Base",
      "slug": "base-mainnet"
    },
    "wallet": {
      "id": "addr_123e4567",
      "name": "Customer Deposit Address",
      "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
      "masterWalletId": "master_123e4567"
    },
    "rawContract": {
      "address": "0x08210F9170F89Ab7658F0B5E3fF39b0E03C594D4",
      "decimals": 6,
      "rawValue": "100500000"
    }
  }
}

Response Requirements

Your webhook endpoint should respond with a status code in the 2xx range to indicate successful delivery:

Status Code	Meaning	Action
2xx (200-299)	Success	Event marked as delivered, no further retries
4xx (400-499)	Client Error	Event marked as failed, will not be retried (unless it’s a temporary issue)
5xx (500-599)	Server Error	Event will be retried according to the retry schedule
Timeout/Network Error	Network Issue	Event will be retried according to the retry schedule

Best Practice: Respond with a 2xx status code as quickly as possible. If you need to perform heavy processing, consider using a queue system to process the webhook asynchronously and return a 202 Accepted response.

Setting Up Webhooks

Via Dashboard

Navigate to Webhooks

Go to Settings > Webhooks in the dashboard

Create Webhook

Click the Create Webhook button

Configure Webhook

Fill in the webhook details:

URL: Your endpoint URL (must be HTTPS)
Name: A descriptive name
Event Types: Select the events you want to receive

Copy Secret

Copy the generated webhook secret for signature verification

Save and Test

Click Save and test your webhook with a test event

Via API

curl -X POST https://api.xentfi.com/v1/webhooks \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/xentfi",
    "name": "Production Webhook",
    "eventTypes": [
      "address.incoming_transfer",
      "address.swap_executed",
      "address.swap_failed",
      "address.transfer_executed",
      "address.transfer_failed",
      "address.signed_success",
      "address.signed_failed",
      "address.created",
      "address.updated"
    ]
  }'

Response:

{
    "data": {
        "id": "webhook_123e4567-e89b-12d3-a456-426614174000",
        "name": "Production Webhook",
        "description": null,
        "developerId": "dev_123e4567",
        "url": "https://yourapp.com/webhooks/xentfi",
        "eventTypes": [
            "address.incoming_transfer",
            "address.swap_executed",
            "address.swap_failed",
            "address.transfer_executed",
            "address.transfer_failed",
            "address.signed_success",
            "address.signed_failed",
            "address.created",
            "address.updated"
        ],
        "secret": "whsec_abc123def456ghi789jkl...",
        "isActive": true,
        "createdAt": "2024-01-15T10:30:00.000Z",
        "updatedAt": "2024-01-15T10:30:00.000Z"
    }
}

Managing Webhooks

List Webhooks

curl -X GET https://api.xentfi.com/v1/webhooks \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -G \
  -d "limit=10" \
  -d "offset=0" \
  -d "isActive=true" \
  -d "order=DESC"

Get Webhook Details

curl -X GET https://api.xentfi.com/v1/webhooks/{subscriptionId} \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id"

Update Webhook

curl -X PUT https://api.xentfi.com/v1/webhooks/{subscriptionId} \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/new-endpoint",
    "isActive": true,
    "eventTypes": [
      "address.incoming_transfer",
      "address.swap_executed",
      "address.swap_failed"
    ]
  }'

Rotate Webhook Secret

curl -X POST https://api.xentfi.com/v1/webhooks/{subscriptionId}/secret/rotate \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id"

Send Test Webhook Event

curl -X POST https://api.xentfi.com/v1/webhooks/{subscriptionId}/test \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "address.incoming_transfer"
  }'

Response:

{
    "success": true,
    "data": {
        "eventId": "test_evt_123e4567-e89b-12d3-a456-426614174000",
        "deliveryStatus": "SUCCESS",
        "statusCode": 200,
        "timestamp": "2024-01-15T10:30:00.000Z"
    }
}

Retry Logic

Retry Schedule

Attempt	Delay	Total Wait
1	Immediate	0 seconds
2	5 seconds	5 seconds
3	30 seconds	35 seconds
4	5 minutes	5 minutes 35 seconds
5	30 minutes	35 minutes 35 seconds
6	1 hour	1 hour 35 minutes
7	2 hours	3 hours 35 minutes
8	6 hours	9 hours 35 minutes

Webhook Events & Retries

You can monitor webhook event delivery status:

curl -X GET https://api.xentfi.com/v1/webhook-events \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -G \
  -d "subscriptionId=webhook_123e4567" \
  -d "limit=10" \
  -d "status=FAILED"

Response:

{
    "data": [
        {
            "id": "event_123e4567-e89b-12d3-a456-426614174000",
            "type": "address.incoming_transfer",
            "payload": { ... },
            "status": "FAILED",
            "responseStatusCode": 500,
            "errorMessage": "Connection timeout",
            "retryCount": 3,
            "createdAt": "2024-01-15T10:30:00.000Z",
            "updatedAt": "2024-01-15T10:35:00.000Z"
        }
    ],
    "total": 1,
    "hasMore": false
}

Get Webhook Event Details

curl -X GET https://api.xentfi.com/v1/webhook-events/{eventId} \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id"

Best Practices

Always verify signatures - Never trust unverified webhooks
Respond quickly - Return 2xx within 5 seconds
Idempotent processing - Handle duplicate webhooks gracefully
Log all webhooks - Keep audit trail for debugging
Monitor failures - Set up alerts for failed deliveries
Queue processing - Use message queues for async handling
Keep endpoints public - Must be accessible from the internet

Webhook Headers

Header	Description	Example
`apiKey`	Your API key for authentication	`xentfi_live_abc123...`
`orgId`	Your organization ID	`org_123e4567`

Event Delivery Status

Status	Description
`PENDING`	Event queued for delivery
`SUCCESS`	Delivered successfully (2xx response)
`FAILED`	Delivery failed (non-2xx response)

Troubleshooting

Webhook not received

Possible causes:

Endpoint not publicly accessible
Firewall blocking requests
Invalid URL format
Webhook not active

Solutions:

Verify URL is accessible from internet
Check firewall rules
Ensure URL includes https://
Verify webhook is active in dashboard

Signature verification fails

Possible causes:

Wrong secret used
Payload body modified
Encoding issues

Solutions:

Rotate and update secret
Use raw request body
Verify JSON stringification

Duplicate webhooks received

Solutions:

Implement idempotency using webhook ID
Check for processed flag in your database
Use unique constraint on webhook ID

High latency responses

Solutions:

Process webhooks asynchronously
Use message queue (RabbitMQ, SQS)
Return 202 Accepted for long processing

API Reference

Endpoint	Method	Description
`/v1/webhooks`	GET	List webhook subscriptions
`/v1/webhooks`	POST	Create webhook subscription
`/v1/webhooks/{subscriptionId}`	GET	Get webhook details
`/v1/webhooks/{subscriptionId}`	PUT	Update webhook
`/v1/webhooks/{subscriptionId}/secret/rotate`	POST	Rotate webhook secret
`/v1/webhooks/{subscriptionId}/test`	POST	Send test webhook event
`/v1/webhook-events`	GET	List webhook events
`/v1/webhook-events/{eventId}`	GET	Get webhook event details

Payment Links

Payment event notifications

Auto Settlement

Settlement event notifications

Master Wallets

Wallet event notifications

Next Steps

Set up your webhook endpoint in API Reference
Register your webhook with XentFi
Monitor webhook deliveries in dashboard

​Overview

​Why Use Webhooks?

⚡ Real-time Updates

🔄 Automatic Retries

🔒 Secure Verification

📊 Event Logging

🎯 Selective Events

🚀 Scalable

​Event Types

​Wildcard Subscriptions

​Address Events

​Master Wallet Events

​Payment Link Events

​Payment Link Transfer Events

​Address Settlement Rule Events

​Master Settlement Rule Events

​Webhook Payloads

​Webhook Headers

​Request Headers

​Signature Format

​Signature Verification Example

​Important Security Notes

​Example Webhook Delivery Request

​Response Requirements

​Setting Up Webhooks

​Via Dashboard

​Via API

​Managing Webhooks

​List Webhooks

​Get Webhook Details

​Update Webhook

​Rotate Webhook Secret

​Send Test Webhook Event

​Retry Logic

​Retry Schedule

​Webhook Events & Retries

​Get Webhook Event Details

​Best Practices

​Webhook Headers

​Event Delivery Status

​Troubleshooting

​API Reference

​Related Products

Payment Links

Auto Settlement

Master Wallets

​Next Steps

Overview

Why Use Webhooks?

Event Types

Wildcard Subscriptions

Address Events

Master Wallet Events

Payment Link Events

Payment Link Transfer Events

Address Settlement Rule Events

Master Settlement Rule Events

Webhook Payloads

Webhook Headers

Request Headers

Signature Format

Signature Verification Example

Important Security Notes

Example Webhook Delivery Request

Response Requirements

Setting Up Webhooks

Via Dashboard

Via API

Managing Webhooks

List Webhooks

Get Webhook Details

Update Webhook

Rotate Webhook Secret

Send Test Webhook Event

Retry Logic

Retry Schedule

Webhook Events & Retries

Get Webhook Event Details

Best Practices

Webhook Headers

Event Delivery Status

Troubleshooting

API Reference

Related Products

Next Steps