Webhooks

Set up real-time notifications for your Hixbe integration

Webhook Overview

Webhooks allow your application to receive real-time notifications about events in your Hixbe account, eliminating the need for constant polling.

How Webhooks Work

1. Event Occurs: Something happens in your Hixbe account (payment succeeds, SMS delivers, credential issues)
2. Notification Sent: Hixbe 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: Hixbe marks the webhook as successfully delivered

Setting Up Webhooks

Payment Gateway Webhooks

1. Create a webhook endpoint

   Create an HTTPS endpoint in your application to receive webhook events:

   // 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 });
   });
   
2. Register webhook in dashboard

   1. Go to dash.hixbe.com
   2. Navigate to Webhooks section
   3. Click “Create Webhook”
   4. Enter your endpoint URL
   5. Select event types to listen for
3. Test your webhook

   Use the dashboard to send test events to your endpoint.

SMS Gateway Webhooks

1. Set up delivery tracking

   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 });
   });
   
2. Register SMS webhook

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

Certification Webhooks

1. Handle credential events

   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

Event	Description	Payload
payment_intent.succeeded	Payment completed successfully	PaymentIntent object
payment_intent.payment_failed	Payment failed	PaymentIntent with failure reason
payment_intent.canceled	Payment was canceled	PaymentIntent object
refund.succeeded	Refund processed successfully	Refund object
customer.created	New customer created	Customer object

SMS Events

Event	Description	Payload
message.sent	SMS message sent	Message object with ID
message.delivered	SMS delivered to recipient	Delivery confirmation
message.failed	SMS delivery failed	Failure reason and details
balance.low	SMS balance running low	Current balance info

Certification Events

Event	Description	Payload
credential.issued	New credential issued	Credential details
credential.verified	Credential verification completed	Verification result
credential.revoked	Credential revoked	Revocation details
badge.earned	Badge earned by recipient	Badge information

Webhook Security

Verify Webhook Signatures

Always verify webhook signatures to ensure requests come from Hixbe and haven’t been tampered with.

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

All webhook payloads follow a consistent structure:

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

Handling Webhook Failures

Retry Logic

Hixbe automatically retries failed webhook deliveries:

• 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

Status Code	Action
200-299	Success - no retry
300-399	Success - no retry
400-499	Failure - no retry (client error)
500-599	Failure - retry with backoff

Manual Retry

Failed webhooks can be manually retried from your dashboard.

Testing Webhooks

Use RequestBin for Testing

For initial testing, use services like RequestBin or ngrok:

# 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

Use the dashboard to send test events to your webhook endpoint.

Monitoring and Debugging

Webhook Logs

Access webhook delivery logs in your dashboard:

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

Common Issues

Webhook not receiving events

• Check endpoint URL is correct and accessible
• Ensure HTTPS is used (HTTP not supported)
• Verify firewall allows incoming connections

Invalid signature errors

• Confirm webhook secret is correct
• Check signature verification implementation
• Ensure raw request body is used for signature calculation

Duplicate events

• Implement idempotency using event IDs
• Store processed event IDs in your database
• Return success quickly to prevent retries

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?

Troubleshooting

Common webhook issues and solutions

Error Handling

Handle webhook errors gracefully

Best Practices

Webhook security and reliability

API Reference

Complete webhook API documentation