Webhooks Guide

Receive real-time notifications about events happening in your Looping Binary integration using webhooks.

What are Webhooks?

Webhooks are HTTP callbacks that notify your server when specific events occur. Instead of polling our API, we send real-time updates directly to your endpoint whenever a transaction, user registration, or other event happens.

Available Webhook Events

transaction.created

Triggered when any coin transaction is created (minting, burning, transfers, etc.)

user.registered

Triggered when a new user creates an account

user.verified

Triggered when a user verifies their email address

balance.updated

Triggered when a user's coin balance changes

treasury.updated

Triggered when a treasury balance changes

Setting Up Webhooks

•Your webhook endpoint URL (must be HTTPS)
•Events you want to subscribe to
•Your application details

Creating a Webhook Endpoint

Here's how to create a webhook handler on your server:

Node.js/Express

const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

// Webhook endpoint
app.post('/webhooks/looping-binary', (req, res) => {
  const signature = req.headers['x-lb-signature'];
  const payload = JSON.stringify(req.body);
  
  // Verify webhook signature
  const expectedSignature = crypto
    .createHmac('sha256', process.env.LB_WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');
  
  if (signature !== expectedSignature) {
    return res.status(401).json(({ error: 'Invalid signature' }));
  }
  
  // Process webhook event
  const { event, data } = req.body;
  
  switch (event) {
    case 'transaction.created':
      handleTransactionCreated(data);
      break;
    case 'user.registered':
      handleUserRegistered(data);
      break;
    case 'balance.updated':
      handleBalanceUpdated(data);
      break;
    default:
      console.log(`Unknown event: $${event}`);
  }
  
  // Always return 200 to acknowledge receipt
  res.status(200).json(({ received: true }));
});

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

Webhook Payload Examples

Transaction Created

{
  "event": "transaction.created",
  "data": {
    "id": 12345,
    "type": "TRANSFER",
    "amount": 50,
    "fromUserId": 123,
    "toUserId": 456,
    "reason": "Payment for service",
    "createdAt": "2025-10-02T19:30:00Z"
  },
  "timestamp": "2025-10-02T19:30:01Z"
}

User Registered

{
  "event": "user.registered",
  "data": {
    "id": 789,
    "email": "newuser@example.com",
    "fullName": "John Doe",
    "role": "USER",
    "isVerified": false,
    "createdAt": "2025-10-02T19:30:00Z"
  },
  "timestamp": "2025-10-02T19:30:01Z"
}

Balance Updated

{
  "event": "balance.updated",
  "data": {
    "userId": 123,
    "previousBalance": 100,
    "newBalance": 150,
    "change": 50,
    "updatedAt": "2025-10-02T19:30:00Z"
  },
  "timestamp": "2025-10-02T19:30:01Z"
}

Webhook Best Practices

Always verify webhook signatures for security
Return 200 status immediately to acknowledge receipt
Process webhooks asynchronously (use queue)
Implement idempotency to handle duplicate events
Log all webhook events for debugging
Use HTTPS endpoints only
Handle webhook failures gracefully

Retry Policy

If your endpoint doesn't respond with a 200 status, we'll retry:

Immediately after failure
After 5 minutes
After 30 minutes
After 2 hours
After 12 hours

After 5 failed attempts, the webhook will be marked as failed and you'll receive an email notification.