Skip to main content

Step-by-Step Setup

1

Create Endpoint

Build POST endpoint to receive webhooks
app.post('/webhooks/killb', async (req, res) => {
  // Handle webhook
  res.status(200).json({ received: true });
});
2

Verify Signatures

Implement HMAC verification
import { createHash } from 'node:crypto';

const verifySignature = (payload, expectedSignature, secret) => {
  const signature = createHash('sha256')
    .update(`${JSON.stringify(req.body)}_${my_secret}`)
    .digest('hex');

  return signature === expectedSignature;
}
3

Register Webhook

Configure in KillB
POST /api/v2/webhooks
{
  "url": "https://api.yourapp.com/webhooks/killb",
  "secret": "your-secret-key",
  "events": ["RAMP", "USER"]
}
4

Test

Create test ramp and verify webhook receipt

Complete Implementation

import express from 'express';
import { createHash } from 'node:crypto';

const app = express();

app.use(express.json());

app.post('/webhooks/killb', async (req, res) => {
  try {
    // 1. Verify signature
    const signature = req.headers['x-signature-sha256'];
    
    const expectedSignature = createHash('sha256')
      .update(`${JSON.stringify(req.body)}_${process.env.WEBHOOK_SECRET}`)
      .digest('hex');
    
    if (signature !== expectedSignature) {
      console.error('Invalid signature');
      return res.status(401).json({ error: 'Invalid signature' });
    }
    
    // 2. Acknowledge immediately
    res.status(200).json({ received: true });
    
    // 3. Process asynchronously
    processWebhookAsync(req.body).catch(console.error);
    
  } catch (error) {
    console.error('Webhook error:', error);
    res.status(500).json({ error: 'Processing failed' });
  }
});

const processWebhookAsync = async (event) => {
  console.log('Processing event:', event.event);
  
  switch(event.event) {
    case 'ramp.completed':
      await handleRampCompleted(event.data);
      break;
    case 'ramp.failed':
      await handleRampFailed(event.data);
      break;
    case 'user.kyc_approved':
      await handleKYCApproved(event.data);
      break;
  }
};

app.listen(3000);

Register Webhook

curl --request POST \
  --url https://teste-94u93qnn.uc.gateway.dev/api/v2/webhooks \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://api.yourapp.com/webhooks/killb",
    "secret": "your-secret-key-at-least-32-chars",
    "events": ["RAMP", "USER", "ACCOUNT"]
  }'

Testing Locally

Use ngrok for local testing:
# Start local server
npm start

# Expose via ngrok
ngrok http 3000

# Use ngrok URL
# https://abc123.ngrok.io/webhooks/killb

Next Steps