Webhooks - XentFi API Documentation

Overview

Why Use Webhooks?

⚡ Real-time Updates

Receive notifications instantly when events happen, not minutes later

🔄 Automatic Retries

Failed deliveries are automatically retried with exponential backoff

🔒 Secure Verification

Every webhook includes a signature to verify authenticity

📊 Event Logging

Complete history of all webhook deliveries for debugging

🎯 Selective Events

Subscribe only to the events you care about

🚀 Scalable

Handle high-volume event streams without performance impact

How Webhooks Work

Event Types

Payment Events

Event	Trigger	Description
`payment.created`	Payment link opened	Payment intent created, awaiting customer action
`payment.processing`	Payment submitted	Transaction broadcast to blockchain
`payment.completed`	Transaction confirmed	Payment successfully processed
`payment.failed`	Payment failed	Transaction failed (insufficient funds, etc.)
`payment.expired`	Session timeout	Payment session expired (deposit method)

Settlement Events

Event	Trigger	Description
`settlement.created`	Rule triggered	Auto-settlement rule activated
`settlement.processing`	Transfer initiated	Settlement transaction broadcast
`settlement.completed`	Transfer confirmed	Funds moved to destination
`settlement.failed`	Transfer failed	Settlement failed (gas, network)
`settlement.swept`	Batch complete	Batch settlement finished

Transfer & Swap Events

Event	Trigger	Description
`transfer.quoted`	Quote generated	Transfer quote created
`transfer.started`	Execution started	Transfer initiated
`transfer.confirmed`	Transaction confirmed	Transfer completed on source chain
`transfer.completed`	Cross-chain done	Bridge transfer fully complete
`transfer.failed`	Transfer failed	Execution failed

Wallet Events

Event	Trigger	Description
`wallet.created`	New wallet	Master wallet created
`address.created`	New address	Deposit address generated
`monitoring.enabled`	Monitoring on	Address monitoring activated
`monitoring.disabled`	Monitoring off	Address monitoring deactivated

Compliance Events

Event	Trigger	Description
`aml.screening`	Address check	AML screening performed
`aml.blocked`	Sanctions match	Address blocked due to sanctions
`aml.review`	Risk alert	High-risk address requires review

Webhook Payloads

Payment Completed Example

{
    "id": "evt_123e4567-e89b-12d3-a456-426614174000",
    "type": "payment.completed",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "data": {
        "paymentIntent": {
            "id": "intent_123",
            "paymentLinkId": "link_456",
            "amount": "100",
            "currency": "USD",
            "tokenAmount": "0.02857",
            "asset": "ETH",
            "blockchain": "eth-mainnet",
            "status": "completed",
            "transactionHash": "0xabc123def456...",
            "senderAddress": "0xSender...",
            "recipientAddress": "0xRecipient..."
        }
    }
}

Settlement Completed Example

{
    "id": "evt_789",
    "type": "settlement.completed",
    "createdAt": "2024-01-15T10:35:00.000Z",
    "data": {
        "settlement": {
            "id": "settle_123",
            "ruleId": "rule_456",
            "sourceAddress": "0xSource...",
            "destinationAddress": "0xDest...",
            "amount": "500",
            "asset": "USDC",
            "transactionHash": "0xdef456...",
            "gasUsed": "0.002",
            "gasPrice": "25"
        }
    }
}

Compliance Alert Example

{
    "id": "evt_789",
    "type": "aml.blocked",
    "createdAt": "2024-01-15T10:40:00.000Z",
    "data": {
        "screening": {
            "address": "0xSanctionedAddress...",
            "riskScore": 100,
            "riskLevel": "CRITICAL",
            "reason": "OFAC sanctions match",
            "identifications": [
                {
                    "category": "sanctions",
                    "name": "Entity Name",
                    "description": "OFAC sanctions designation"
                }
            ]
        }
    }
}

Setting Up Webhooks

Create Webhook Endpoint

First, create an endpoint in your application to receive webhooks:

// Node.js example
app.post('/webhooks/xentfi', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = req.body;

  // Verify signature
  if (!verifySignature(payload, signature)) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook
  switch(payload.type) {
    case 'payment.completed':
      handlePaymentCompleted(payload.data);
      break;
    case 'settlement.completed':
      handleSettlementCompleted(payload.data);
      break;
    default:
      console.log(`Unhandled event: ${payload.type}`);
  }

  res.status(200).send('OK');
});

Register Webhook

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",
    "events": ["payment.completed", "settlement.completed", "aml.blocked"],
    "secret": "your-webhook-secret"
  }'

{
    "success": true,
    "data": {
        "id": "webhook_123e4567",
        "url": "https://yourapp.com/webhooks/xentfi",
        "events": [
            "payment.completed",
            "settlement.completed",
            "aml.blocked"
        ],
        "secret": "whsec_abc123...",
        "isActive": true,
        "createdAt": "2024-01-15T10:30:00.000Z"
    }
}

Signature Verification

Why Verify Signatures?

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

Verification Process

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

Retry Headers

Header	Description
`X-Retry-Count`	Current retry attempt number
`X-Retry-Delay`	Seconds until next retry
`X-Previous-Response`	HTTP status from last attempt

Managing Webhooks

List Webhooks

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

Update Webhook

curl -X PUT https://api.xentfi.com/v1/webhooks/{webhookId} \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/new-endpoint",
    "events": ["payment.completed"],
    "isActive": true
  }'

Delete Webhook

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

Rotate Webhook Secret

curl -X POST https://api.xentfi.com/v1/webhooks/{webhookId}/rotate-secret \
  -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
Use idempotency keys - Prevent duplicate processing
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 Delivery Monitoring

Available Metrics

Metric	Description	Update Frequency
Total deliveries	Number of webhooks sent	Real-time
Success rate	Percentage of 2xx responses	Real-time
Failed deliveries	Non-2xx responses	Real-time
Average latency	Time to receive response	Hourly
Retry queue size	Pending retries	Real-time
Dead letters	Failed after all retries	Real-time

Testing Webhooks Locally

Using ngrok

# Install ngrok
brew install ngrok

# Expose your local server
ngrok http 3000

# Copy the HTTPS URL (e.g., https://abc123.ngrok.io)
# Use this URL when creating your webhook

Test Payloads

# Simulate a webhook for testing
curl -X POST https://yourapp.com/webhooks/xentfi \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: test_signature" \
  -d '{
    "id": "test_evt_123",
    "type": "payment.completed",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "data": {
      "paymentIntent": {
        "id": "test_intent_123",
        "amount": "100",
        "status": "completed"
      }
    }
  }'

Event Filtering

{
    "url": "https://yourapp.com/webhooks",
    "events": [
        "payment.completed",
        "settlement.completed",
        "aml.blocked"
    ]
}

Wildcard Subscriptions

Pattern	Matches
`payment.*`	All payment events
`settlement.*`	All settlement events
`*.completed`	All completion events
`*`	All events

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
Paybody 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

Webhook Headers

Header	Description	Example
`X-Webhook-Signature`	HMAC-SHA256 signature	`a1b2c3d4e5f6...`
`X-Webhook-ID`	Unique webhook identifier	`whk_123e4567`
`X-Event-Type`	Type of event	`payment.completed`
`X-Event-ID`	Unique event identifier	`evt_123e4567`
`X-Retry-Count`	Retry attempt number	`0`
`X-Timestamp`	Event timestamp	`1705319400`
`User-Agent`	Identifies XentFi	`XentFi-Webhook/1.0`

Pricing

Feature	Starter	Professional	Business	Enterprise
Webhooks	5	25	100	Unlimited
Events per webhook	10	25	50	Unlimited
Retry attempts	3	5	8	10
Retention period	7 days	30 days	90 days	1 year
Custom retry schedule	❌	❌	✅	✅
Dead letter queue	❌	❌	✅	✅

Performance Metrics

Metric	Target	Description
Delivery time	< 500ms	Time from event to delivery
Success rate	> 99.9%	Successful deliveries
Retry rate	< 1%	Percentage requiring retry
Availability	99.99%	Webhook system uptime

Payment Links

Payment event notifications

Auto Settlement

Settlement event notifications

AML Compliance

Compliance alert notifications

Next Steps

Set up your webhook endpoint in API Reference
Register your webhook with XentFi
Verify signatures for security
Monitor webhook deliveries in dashboard

Documentation Index

​Overview

​Why Use Webhooks?

⚡ Real-time Updates

🔄 Automatic Retries

🔒 Secure Verification

📊 Event Logging

🎯 Selective Events

🚀 Scalable

​How Webhooks Work

​Event Types

​Payment Events

​Settlement Events

​Transfer & Swap Events

​Wallet Events

​Compliance Events

​Webhook Payloads

​Payment Completed Example

​Settlement Completed Example

​Compliance Alert Example

​Setting Up Webhooks

​Create Webhook Endpoint

​Register Webhook

​Signature Verification

​Why Verify Signatures?

​Verification Process

​Verification Code Example

​Retry Logic

​Retry Schedule

​Retry Headers

​Managing Webhooks

​List Webhooks

​Update Webhook

​Delete Webhook

​Rotate Webhook Secret

​Best Practices

​Webhook Delivery Monitoring

​Available Metrics

​Testing Webhooks Locally

​Using ngrok

​Test Payloads

​Event Filtering

​Subscribe to Specific Events

​Wildcard Subscriptions

​Troubleshooting

​Webhook Headers

​Pricing

​Performance Metrics

​Related Products

Payment Links

Auto Settlement

AML Compliance

​Next Steps

Overview

Why Use Webhooks?

How Webhooks Work

Event Types

Payment Events

Settlement Events

Transfer & Swap Events

Wallet Events

Compliance Events

Webhook Payloads

Payment Completed Example

Settlement Completed Example

Compliance Alert Example

Setting Up Webhooks

Create Webhook Endpoint

Register Webhook

Signature Verification

Why Verify Signatures?

Verification Process

Verification Code Example

Retry Logic

Retry Schedule

Retry Headers

Managing Webhooks

List Webhooks

Update Webhook

Delete Webhook

Rotate Webhook Secret

Best Practices

Webhook Delivery Monitoring

Available Metrics

Testing Webhooks Locally

Using ngrok

Test Payloads

Event Filtering

Subscribe to Specific Events

Wildcard Subscriptions

Troubleshooting

Webhook Headers

Pricing

Performance Metrics

Related Products

Next Steps