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

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_transfer.created`	Transfer initiated	Payment link transfer created
`payment_link_transfer.updated`	Transfer updated	Payment link transfer status changed

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

Wildcard Subscriptions

Pattern	Matches
`address.*`	All address events
`master.*`	All master wallet events
`payment_link.*`	All payment link events
`payment_link_transfer.*`	All payment link transfer events
`*`	All events

Webhook Payloads

Address Incoming Transfer Example

{
    "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"
        }
    }
}

Master Swap Executed Example

{
    "id": "evt_456e7890",
    "type": "master.swap_executed",
    "version": "1.0",
    "timestamp": "2024-01-15T10:35:00.000Z",
    "environment": "prod",
    "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"
    }
}

Payment Link Created Example

{
    "id": "evt_789e0123",
    "type": "payment_link.created",
    "version": "1.0",
    "timestamp": "2024-01-15T10:40:00.000Z",
    "environment": "prod",
    "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"
        }
    }
}

Settlement Rule Executed Example

{
    "id": "evt_234e5678",
    "type": "master_settlement_rule.executed",
    "version": "1.0",
    "timestamp": "2024-01-15T10:45:00.000Z",
    "environment": "prod",
    "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": "master_123e4567",
            "name": "Main Treasury"
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base"
        },
        "txhash": "0x28a1bfa727a024dd450352e736f957ac6f08471825362130ef1c3b4da536ebfb",
        "amount": "100.00",
        "asset": {
            "id": "69d851b9-c358-4359-becd-3e614ca1ab4d",
            "symbol": "EURC"
        }
    }
}

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": [
      "DEPOSITE_INCOMING_DETECTED",
      "SWAP_EXECUTED",
      "SWAP_FAILED",
      "TRANSFER_EXECUTED",
      "TRANFER_FAILED",
      "SIGNED_SUCCESS",
      "SIGNED_FAILED",
      "DEPOSITE_ADDRESS_CREATED"
    ]
  }'

Response:

{
    "data": {
        "id": "webhook_123e4567-e89b-12d3-a456-426614174000",
        "name": "Production Webhook",
        "description": null,
        "developerId": "dev_123e4567",
        "url": "https://yourapp.com/webhooks/xentfi",
        "eventTypes": [
            "DEPOSITE_INCOMING_DETECTED",
            "SWAP_EXECUTED",
            "SWAP_FAILED",
            "TRANSFER_EXECUTED",
            "TRANFER_FAILED",
            "SIGNED_SUCCESS",
            "SIGNED_FAILED",
            "DEPOSITE_ADDRESS_CREATED"
        ],
        "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"

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": [
      "DEPOSITE_INCOMING_DETECTED",
      "SWAP_EXECUTED"
    ]
  }'

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"

Signature Verification

Why Verify Signatures?

Webhook signatures ensure that requests truly come from XentFi and not an imposter.

Verification Code Example

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

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": "DEPOSITE_INCOMING_DETECTED",
            "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/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

​Address Events

​Master Wallet Events

​Payment Link Events

​Payment Link Transfer Events

​Address Settlement Rule Events

​Master Settlement Rule Events

​Wildcard Subscriptions

​Webhook Payloads

​Address Incoming Transfer Example

​Master Swap Executed Example

​Payment Link Created Example

​Settlement Rule Executed Example

​Setting Up Webhooks

​Via Dashboard

​Via API

​Managing Webhooks

​List Webhooks

​Get Webhook Details

​Update Webhook

​Rotate Webhook Secret

​Signature Verification

​Why Verify Signatures?

​Verification Code Example

​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

Address Events

Master Wallet Events

Payment Link Events

Payment Link Transfer Events

Address Settlement Rule Events

Master Settlement Rule Events

Wildcard Subscriptions

Webhook Payloads

Address Incoming Transfer Example

Master Swap Executed Example

Payment Link Created Example

Settlement Rule Executed Example

Setting Up Webhooks

Via Dashboard

Via API

Managing Webhooks

List Webhooks

Get Webhook Details

Update Webhook

Rotate Webhook Secret

Signature Verification

Why Verify Signatures?

Verification Code Example

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