LuxuryX
Developer

Webhooks & Event APIs

Integrate with LuxuryX in real-time using webhooks and event-driven APIs. Receive instant notifications for transactions, portfolio changes, and system events.

Webhook Fundamentals

Webhooks allow your application to subscribe to real-time events from the LuxuryX platform. Instead of polling our API repeatedly, we push events directly to your configured endpoint whenever something relevant happens.

⚡ Real-Time

Events delivered within milliseconds of occurrence

🔄 Reliable Delivery

Automatic retries with exponential backoff

✓ Verified

HMAC signature verification for authenticity

Event Types

Transaction Events

  • • transaction.created – New transaction initiated
  • • transaction.confirmed – Transaction confirmed on-chain
  • • transaction.failed – Transaction failed or reverted
  • • transaction.completed – Transaction finalized
  • • transaction.status_changed – Status update

Portfolio Events

  • • portfolio.updated – Holdings changed
  • • portfolio.balance_changed – Balance update
  • • asset.transferred – Asset transfer received
  • • staking.reward_earned – Staking reward accrued
  • • position.opened – New position created

Account Events

  • • account.created – Account registration
  • • account.verified – KYC completed
  • • account.upgraded – Account tier upgraded
  • • account.disabled – Account suspended
  • • security.alert – Security event detected

Compliance Events

  • • compliance.review_required – Review needed
  • • compliance.approved – Compliance approved
  • • compliance.rejected – Application rejected
  • • sanctions.screen_updated – Screening result
  • • aml.alert – AML alert triggered

Setting Up Webhooks

Configuration Steps

  1. 1. Navigate to Developer Dashboard
  2. 2. Select "Webhooks" from menu
  3. 3. Click "Add Webhook Endpoint"
  4. 4. Enter your HTTPS URL
  5. 5. Select event types to subscribe
  6. 6. Copy the signing secret
  7. 7. Test the endpoint

Best Practices

  • ✓ Use HTTPS endpoints only
  • ✓ Verify webhook signatures always
  • ✓ Process webhooks asynchronously
  • ✓ Implement idempotency handling
  • ✓ Log all webhook events
  • ✓ Set reasonable timeouts (5-10s)
  • ✓ Return 200 OK immediately
  • ✓ Monitor endpoint health

Event Payload Structure

All webhooks follow the same base structure:

{
  "id": "evt_abc123xyz789",
  "type": "transaction.confirmed",
  "timestamp": 1723638461000,
  "version": "1.0",
  "signature": "sha256=...",
  "data": {
    "transaction_id": "txn_...",
    "status": "confirmed",
    "amount": "1000.00",
    "currency": "USD",
    "confirmations": 12,
    "block_hash": "0x...",
    "timestamp": 1723638400000
  }
}

Signature Verification

Each webhook is signed with an HMAC-SHA256 signature. Verify it using your webhook secret:

const signature = req.headers['x-webhook-signature'];
const timestamp = req.headers['x-webhook-timestamp'];
const body = JSON.stringify(req.body);

const expected = crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(`${timestamp}.${body}`)
  .digest('hex');

if (signature !== expected) {
  return res.status(401).json({ error: 'Invalid signature' });
}

Retry & Error Handling

Automatic Retries

  • • Attempt 1: Immediate
  • • Attempt 2: +5 seconds
  • • Attempt 3: +30 seconds
  • • Attempt 4: +2 minutes
  • • Attempt 5: +15 minutes
  • • Max attempts: 5 total
  • • Window: 24 hours

HTTP Status Codes

  • • 200-299: Success, don't retry
  • • 408, 429, 5xx: Retry with backoff
  • • 4xx (except 408): Fail, don't retry
  • • Timeout (>30s): Treat as failure
  • • Return response body for debugging

Need Help With Webhooks?

Consult our complete API documentation or contact developer support for assistance with webhook integration.

Developer Support API Documentation