Developer Platform Webhooks

Webhooks allow you to receive real-time notifications about events in your Linka account. This guide explains how to configure and use webhooks.

What are Webhooks?

Webhooks are HTTP callbacks that notify your application when specific events occur in your Linka account. Instead of polling our API, you can receive instant notifications about:

• Payment status changes
• Wallet balance updates
• Transaction completions
• Compliance status changes
• Error events

Setting Up Webhooks

Step 1: Create a Webhook Endpoint

Create an HTTP endpoint in your application that can receive POST requests:

// Example: Express.js endpoint
app.post('/webhooks/linka', async (req, res) => {
  const event = req.body;
  
  // Verify webhook signature
  const signature = req.headers['linka-signature'];
  const isValid = verifyWebhookSignature(event, signature);
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the event
  await handleWebhookEvent(event);
  
  // Always return 200 to acknowledge receipt
  res.status(200).send('OK');
});

Step 2: Configure in Dashboard

1. Go to Developer → Webhooks in your Linka dashboard
2. Click Add Webhook Endpoint
3. Enter your webhook URL (must be HTTPS)
4. Select the events you want to receive:
   • payment.completed
   • payment.failed
   • wallet.balance_updated
   • transaction.status_changed
   • compliance.verification_completed
5. Click Save

Step 3: Verify Webhook Signature

All webhook requests include a signature header for verification:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const computed = hmac.update(JSON.stringify(payload)).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(computed)
  );
}

Webhook Event Structure

All webhook events follow this structure:

{
  "id": "evt_1234567890",
  "type": "payment.completed",
  "created": 1640995200,
  "data": {
    "object": "payment",
    "id": "pay_abc123",
    "amount": "100.00",
    "currency": "USDC",
    "status": "completed"
  }
}

Event Types

Payment Events

• payment.created: A new payment was initiated
• payment.completed: Payment successfully completed
• payment.failed: Payment failed
• payment.refunded: Payment was refunded

Wallet Events

• wallet.created: New wallet created
• wallet.balance_updated: Wallet balance changed
• wallet.address_generated: New address generated

Transaction Events

• transaction.status_changed: Transaction status updated
• transaction.confirmed: Transaction confirmed on blockchain

Compliance Events

• compliance.verification_started: KYC/KYB verification started
• compliance.verification_completed: Verification completed
• compliance.verification_failed: Verification failed

Testing Webhooks

Use the webhook testing tool in your dashboard:

1. Go to Developer → Webhooks
2. Click on your webhook endpoint
3. Click Send Test Event
4. Verify your endpoint receives the test event

Best Practices

• Always verify webhook signatures to ensure requests are from Linka
• Return 200 OK quickly - process events asynchronously
• Implement idempotency - use event IDs to prevent duplicate processing
• Set up retry logic - webhooks are retried up to 3 times
• Log all events for debugging and audit purposes

Next Steps

• Review API Webhooks Reference for detailed API documentation
• Set up Sandbox Environment for testing webhooks
• Check Common Use Cases for integration examples