Key Operational Concepts

Webhooks

Webhooks allow you to receive real-time notifications about events in your OneLiquidity account (e.g., deposits, withdrawals, transfers).

How Webhooks Work

1. Configure your webhook URL in your integrator settings
2. OneLiquidity sends HTTP POST requests to your URL when events occur
3. Your endpoint responds with HTTP 200/201/204 to acknowledge receipt
4. Automatic retries if your endpoint doesn't respond (up to 72 hours)

Webhook Events

OneLiquidity sends webhooks for the following events:

Deposits & Withdrawals

• WALLET_DEPOSIT_INITIATED - Crypto deposit detected
• WALLET_DEPOSIT_COMPLETED - Crypto deposit confirmed
• WALLET_WITHDRAWAL_PROCESSING - Crypto withdrawal initiated
• WALLET_WITHDRAWAL_COMPLETED - Crypto withdrawal completed
• WALLET_WITHDRAWAL_FAILURE - Crypto withdrawal failed
• WALLET_WITHDRAWAL_REJECTED - Crypto withdrawal rejected
• WALLET_WITHDRAWAL_CANCELLED - Crypto withdrawal cancelled

Transfers

• INTEGRATOR_LEDGER_FUND_TRANSFER - Internal ledger transfer completed
• INTEGRATOR_DEPOSIT_SUCCESS - Fiat deposit successful
• INTEGRATOR_DEPOSIT_SUBMITTED - Fiat deposit submitted
• INTEGRATOR_DEPOSIT_UPDATED - Fiat deposit status updated

Trading

• TRADING_WITHDRAWAL_PROCESSING - Trading withdrawal initiated
• TRADING_WITHDRAWAL_COMPLETED - Trading withdrawal completed
• TRADING_WITHDRAWAL_FAILURE - Trading withdrawal failed

FCAT (Fiat Currency) Events

• FCAT.PAYOUT.COMPLETE - Payout successful
• FCAT.PAYOUT.FAILED - Payout failed
• FCAT.PAYOUT.PROCESSING - Payout in progress
• FCAT.PAYOUT.RETURN - Payout returned
• FCAT.COLLECTION.COMPLETE - Collection (deposit) successful
• FCAT.COLLECTION.FAILED - Collection failed
• FCAT.COLLECTION.PROCESSING - Collection in progress
• FCAT.VIRTUAL_ACCOUNT.APPROVED - Virtual account approved
• FCAT.VIRTUAL_ACCOUNT.DECLINED - Virtual account declined

Account Management

• INTEGRATOR_VERIFICATION_SUCCESS - Email verification completed
• INTEGRATOR_TOKEN_GENERATED - New authentication token generated
• INTEGRATOR_TOKEN_DELETED - Authentication token deleted
• INTEGRATOR_TOKEN_RESET - Authentication token reset
• INTEGRATOR_WEBHOOK_UPDATED - Webhook URL updated

Webhook Payload Structure

All webhook requests include:

Headers:

Content-Type: application/json
X-OneLiquidity-Signature: <HMAC_SHA256_signature>

Body:

{
    "event": "WALLET_DEPOSIT_COMPLETED",
    "data": {
        "depositId": "dep_abc123...",
        "currency": "BTC",
        "amount": "0.05",
        "txId": "abc123def456...",
        "confirmations": 6,
        "timestamp": "2024-11-10T14:30:00.000Z"
    },
    "timestamp": "2024-11-10T14:30:00.000Z",
    "integratorPk": "6d288fc9-f82f-4181-b95a-aa50cd1a9d86"
}

Verifying Webhook Signatures

Critical: Always verify the X-OneLiquidity-Signature header to ensure webhooks are genuine.

Verification Algorithm:

1. Extract the X-OneLiquidity-Signature header
2. Compute HMAC SHA-256 of the raw request body using your integrator PK as the secret
3. Compare your computed signature with the header value

Example Implementation (Node.js):

const crypto = require('crypto')

function verifyWebhookSignature(requestBody, signature, integratorPk) {
    const computedSignature = crypto
        .createHmac('sha256', integratorPk)
        .update(JSON.stringify(requestBody))
        .digest('hex')

    return crypto.timingSafeEqual(
        Buffer.from(signature),
        Buffer.from(computedSignature),
    )
}

// Usage in your webhook endpoint
app.post('/webhooks/oneliquidity', (req, res) => {
    const signature = req.headers['x-oneliquidity-signature']
    const integratorPk = process.env.INTEGRATOR_PK

    if (!verifyWebhookSignature(req.body, signature, integratorPk)) {
        return res.status(401).send('Invalid signature')
    }

    // Process webhook event
    const { event, data } = req.body

    // Respond immediately to acknowledge receipt
    res.status(200).send('OK')

    // Handle event asynchronously
    processWebhookEvent(event, data)
})

Python Example:

import hmac
import hashlib
import json

def verify_webhook_signature(request_body, signature, integrator_pk):
    computed_signature = hmac.new(
        integrator_pk.encode('utf-8'),
        json.dumps(request_body).encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, computed_signature)

Security Note: Signature verification protects against spoofed webhooks and man-in-the-middle attacks.

Webhook Retry Logic

If your endpoint doesn't respond with HTTP 200/201/204, OneLiquidity automatically retries:

• Retry period: Up to 72 hours
• Retry strategy: Exponential backoff
• Queue: Webhooks are queued via AWS SQS for reliable delivery

Best Practice: Respond with 200 OK immediately, then process the webhook asynchronously to avoid timeouts.

Setting Up Your Webhook Endpoint

Requirements:

• Publicly accessible HTTPS URL
• Responds within 15 seconds (timeout limit)
• Returns HTTP 200, 201, or 204 on success
• Verifies X-OneLiquidity-Signature header

Configure Webhook URL:

curl --request PATCH \
  --url "https://api.oneliquidity.technology/integrator/v1" \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "webhookUrl": "https://your-domain.com/webhooks/oneliquidity"
  }'

Rate Limiting

OneLiquidity enforces rate limits to ensure fair usage and system stability.

Rate Limit Thresholds

Per-Service Limits:

• Burst Limit: 2-5 requests per second (varies by service)
• Rate Limit: 1-2 requests per second sustained (varies by service)
• Monthly Quota: 10,000 requests per month

Service-Specific Limits:

Note: These limits apply per integrator account. FCAT endpoints share rate limits with the integrator service. Contact support for higher limits.

Rate Limit Headers

When approaching rate limits, responses may include:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9850
X-RateLimit-Reset: 1699632000

Note: These headers are provided by AWS API Gateway and may not appear on every response. They typically appear when you're approaching or have exceeded your rate limit.

Handling Rate Limits

When you exceed the rate limit, you'll receive:

HTTP 429 - Too Many Requests:

{
    "message": "Too many requests"
}

Recommended Retry Strategy:

async function callApiWithRetry(apiFunction, maxRetries = 3) {
    let retries = 0
    let delay = 1000 // Start with 1 second

    while (retries < maxRetries) {
        try {
            return await apiFunction()
        } catch (error) {
            if (error.status === 429 && retries < maxRetries - 1) {
                retries++
                await new Promise((resolve) => setTimeout(resolve, delay))
                delay *= 2 // Exponential backoff
            } else {
                throw error
            }
        }
    }
}

Timestamps and Timezones

All timestamps in OneLiquidity API responses use ISO 8601 UTC format.

Format: YYYY-MM-DDTHH:mm:ss.sssZ

Example: 2024-11-10T14:30:00.000Z

Timezone: Always UTC (Z suffix)

Working with Timestamps

JavaScript:

const timestamp = '2024-11-10T14:30:00.000Z'
const date = new Date(timestamp)
console.log(date.toLocaleString()) // Converts to local timezone

Python:

from datetime import datetime

timestamp = "2024-11-10T14:30:00.000Z"
date = datetime.fromisoformat(timestamp.replace('Z', '+00:00'))
print(date.isoformat())

Best Practices

API Integration

• Use exponential backoff for transient errors (500, 503)
• Verify webhook signatures before processing events
• Store webhook events for audit trails and debugging
• Respond quickly to webhooks (under 15 seconds) to avoid timeouts
• Implement idempotency in your webhook handlers (same event may be delivered multiple times)

Security

• Never expose your JWT tokens in client-side code
• Rotate tokens regularly for production environments
• Use HTTPS for all webhook endpoints
• Validate all incoming data from webhooks before processing

Performance

• Cache frequently accessed data (account balances, exchange rates)
• Use pagination for large result sets (leverage LEK from Section 4)
• Batch operations when possible to reduce API calls
• Monitor rate limits and adjust request frequency

Error Handling

• Log all API errors with full context for debugging
• Don't retry on 4xx errors (except 429) - fix the request instead
• Implement circuit breakers for external service calls
• Alert on persistent failures (e.g., webhook delivery failures beyond 24 hours)

Testing Webhooks

Local Development

Use webhook testing tools to receive webhooks locally:

• ngrok - Creates secure tunnels to localhost
• webhook.site - Inspect webhook payloads
• Hookbin - Capture and debug webhooks

Example with ngrok:

# Start your local webhook server on port 3000
npm start

# In another terminal, start ngrok
ngrok http 3000

# Use the ngrok URL as your webhook URL
# https://abc123.ngrok.io/webhooks/oneliquidity

Staging Environment

Test webhook integrations in staging before production:

1. Configure webhook URL in staging dashboard
2. Trigger events (deposits, transfers) using test funds
3. Verify webhook delivery and signature validation
4. Test retry logic by temporarily disabling your endpoint

Next Steps

• Production Checklist: Ensure you've completed all integration requirements
• API Reference: Explore all available endpoints at docs.oneliquidity.technology/reference
• Service Guides: Dive into Trading, Payments, or Wallets
• Support: Contact [email protected] for technical assistance