Webhooks

​

Webhook Overview

​

How Webhooks Work

1. Event Occurs: Something happens in your Xerobi account (payment succeeds, SMS delivers, credential issues)
2. Notification Sent: Xerobi sends an HTTP POST request to your configured webhook URL
3. Your App Responds: Your application processes the event and responds with a 200 status code
4. Confirmation: Xerobi marks the webhook as successfully delivered

​

Setting Up Webhooks

​

Payment Gateway Webhooks

// Express.js example
app.post('/webhooks/hixbe', express.raw({ type: 'application/json' }), (req, res) => {
  const event = JSON.parse(req.body);

  // Process the event
  switch (event.type) {
    case 'payment_intent.succeeded':
      handlePaymentSuccess(event.data);
      break;
    case 'payment_intent.payment_failed':
      handlePaymentFailure(event.data);
      break;
  }

  res.json({ received: true });
});

​

SMS Gateway Webhooks

app.post('/webhooks/sms-delivery', (req, res) => {
  const { message_id, status, recipient, timestamp } = req.body;

  // Update message status in your database
  updateMessageStatus(message_id, status);

  res.json({ success: true });
});

curl -X POST "https://api.hixbe.com/sms/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Xerobi-Version: 2026-01-01" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/sms-delivery",
    "events": ["message.delivered", "message.failed"]
  }'

​

Certification Webhooks

app.post('/webhooks/certification', (req, res) => {
  const event = req.body;

  switch (event.type) {
    case 'credential.issued':
      // New credential issued
      break;
    case 'credential.verified':
      // Credential verification completed
      break;
    case 'credential.revoked':
      // Credential has been revoked
      break;
  }

  res.json({ acknowledged: true });
});

​

Webhook Events

​

Payment Events

​

SMS Events

​

Certification Events

​

Webhook Security

​

Verify Webhook Signatures

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

// In your webhook handler
app.post('/webhooks/hixbe', (req, res) => {
  const signature = req.headers['x-hixbe-signature'];
  const secret = process.env.WEBHOOK_SECRET;

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

  // Process webhook...
});

​

Security Best Practices

• Always use HTTPS for webhook endpoints
• Verify webhook signatures on all requests
• Use secret keys unique to each webhook
• Implement idempotency to handle duplicate events
• Validate event data before processing
• Monitor webhook delivery in your dashboard

​

Webhook Payload Format

{
  "id": "evt_1234567890",
  "type": "payment_intent.succeeded",
  "created": 1640995200,
  "data": {
    "object": {
      // Event-specific data
    }
  },
  "api_version": "2026-01-01"
}

​

Handling Webhook Failures

​

Retry Logic

• Immediate retry: After 1 minute
• Exponential backoff: 2, 4, 8, 16 minutes
• Final attempt: After 24 hours
• Expiration: Events expire after 7 days

​

Failure Response Codes

​

Manual Retry

​

Testing Webhooks

​

Use RequestBin for Testing

# Install ngrok
npm install -g ngrok

# Expose local server
ngrok http 3000

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

​

Test Events

​

Monitoring and Debugging

​

Webhook Logs

• Delivery status (success/failure)
• Response time and status codes
• Request/response payloads
• Failure reasons

​

Common Issues

​

Best Practices

• Process webhooks asynchronously to avoid timeouts
• Implement idempotency using event IDs
• Store webhook events for debugging
• Monitor webhook health in your dashboard
• Use different endpoints for different event types
• Test thoroughly in sandbox before production

​

Need Help?