Webhook Setup

Overview

Lucra webhooks enable real-time event notifications via HTTP POST requests to your configured endpoints. This document covers subscription management and request verification.

Prerequisites

• API key from API Setup

• Publicly accessible HTTPS endpoint to receive webhooks

• Shared secret for signature verification (provided by Lucra team)

Webhook Management API

Base Operations

All webhook configuration operations use the same API credentials from your API setup.

Create Webhook Configuration

POST /api/rest/webhook/configs
X-Lucra-Api-Key: <your-api-key>
Content-Type: application/json

{
  "subscriptions": ["UserSignedUp", "FundsDeposited"],
  "url": "https://your-domain.com/webhooks/lucra",
  "name": "Production Webhook",
  "description": "Main webhook endpoint",
  "active": true,
  "customHeaders": {
    "X-Custom-Header": "value"
  },
  "expiresAt": "2025-12-31T23:59:59Z"
}

List Configurations

GET /api/rest/webhook/configs
X-Lucra-Api-Key: <your-api-key>

Update Configuration

PUT /api/rest/webhook/configs/:id
X-Lucra-Api-Key: <your-api-key>
Content-Type: application/json

{
  "subscriptions": ["UserSignedUp", "UserKYCVerified"],
  "active": true
}

Delete Configuration

DELETE /api/rest/webhook/configs/{webhook-uuid}
X-Lucra-Api-Key: <your-api-key>

Available Event Types

Event	Description
UserSignedUp	New user registration
UserKYCVerified	User KYC verification completed
FundsDeposited	User deposited funds
C2CWithdrawal	Convert-to-credit withdrawal initiated
TournamentCreated	Tournament created
TournamentCanceled	Tournament canceled
TournamentCompleted	Tournament completed
TournamentEdited	Tournament modified
TournamentUserJoined	User joined tournament
RecreationalGameCreated	Games You Play game created
RecreationalGameJoined	User joined GYP game
RecreationalGameCanceled	GYP game canceled
RecreationalGameCompleted	GYP game completed
RecreationalGameStarted	GYP game started

Configuration Limits

• Maximum 5 webhook configurations per account

• Single-instance subscriptions: Some events (e.g., C2CWithdrawal) can only exist in one configuration at a time

• Custom headers: Optional headers added to each webhook request

• Expiration: Optionally set expiration date for time-limited webhooks

Request Verification

Overview

All webhook requests include an X-Lucra-Signature header containing an HMAC-SHA256 signature for payload verification.

Signature Format

X-Lucra-Signature: sha256=<hex-encoded-signature>

Verification Steps

1. Extract signature from X-Lucra-Signature header

2. Capture the raw request body (before JSON parsing)

3. Compute HMAC-SHA256 of raw body using your shared secret

4. Compare computed signature with received signature using constant-time comparison

Implementation Example (Node.js)

import crypto from 'crypto';

function verifyWebhookSignature(rawBody: Buffer, signature: string, secret: string): boolean {
  // Validate signature format
  if (!signature.startsWith('sha256=')) {
    return false;
  }

  // Extract hex signature
  const receivedSignature = signature.substring(7);

  // Compute expected signature
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(rawBody);
  const computedSignature = hmac.digest('hex');

  // Constant-time comparison to prevent timing attacks
  if (receivedSignature.length !== computedSignature.length) {
    return false;
  }

  return crypto.timingSafeEqual(Buffer.from(receivedSignature), Buffer.from(computedSignature));
}

// Express.js example
app.post('/webhooks/lucra', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-lucra-signature'] as string;
  const secret = process.env.LUCRA_WEBHOOK_SECRET;

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

  // Parse JSON only after verification
  const payload = JSON.parse(req.body.toString());

  // Process webhook...
  res.status(200).send('OK');
});

Security Best Practices

• Use raw body: Always verify signature against the raw request body before parsing JSON

• Constant-time comparison: Use timing-safe comparison functions to prevent timing attacks

• Secure secret storage: Store shared secrets in environment variables or secret managers

• HTTPS only: Only accept webhooks over HTTPS

• Validate payload structure: Verify expected fields after signature validation

• Idempotency: Handle duplicate webhook deliveries gracefully

Shared Secret Management

• Secrets are provided by the Lucra team upon webhook registration

• Delivered via secure channels (e.g., single-use secret links)

• If compromised, contact Lucra team immediately for rotation

• Each webhook configuration may have a different secret

Event-Specific Webhooks

For detailed payload schemas and event-specific information, see:

• Games You Play Webhooks

• Tournament Webhooks

• Free-to-Play Webhooks

• Convert to Credit Webhooks