> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xerobi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Set up real-time notifications for your Xerobi integration

## Webhook Overview

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

## 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

**1. Create a webhook endpoint**

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

```javascript theme={null}
// 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](https://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**

```javascript theme={null}
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**

```bash theme={null}
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

**1. Handle credential events**

```javascript theme={null}
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

> [!WARNING]
>
> **Always verify webhook signatures** to ensure requests come from Xerobi and haven't been tampered with.

```javascript theme={null}
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:

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

## Handling Webhook Failures

### Retry Logic

Xerobi 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:

```bash theme={null}
# 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

> [accordion] Webhook not receiving events
>
> * Check endpoint URL is correct and accessible
> * Ensure HTTPS is used (HTTP not supported)
> * Verify firewall allows incoming connections

> [accordion] Invalid signature errors
>
> * Confirm webhook secret is correct
> * Check signature verification implementation
> * Ensure raw request body is used for signature calculation

> [accordion] 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?

> [card] [Troubleshooting](https://docs.xerobi.com/faq-guides/troubleshooting)
>
> Common webhook issues and solutions

> [card] [Error Handling](https://docs.xerobi.com/faq-guides/error-handling.md)
>
> Handle webhook errors gracefully

> [card] [Best Practices](https://docs.xerobi.com/faq-guides/best-practices.md)
>
> Webhook security and reliability

> [card] [API Reference](https://docs.xerobi.com/payment-api/introduction.md)
>
> Complete webhook API documentation


## Related topics

- [Register Webhook](https://docs.xerobi.com/sms-api/endpoint/register-webhook.md)
- [Delete webhook](https://docs.xerobi.com/sms-api/endpoint/delete-webhook.md)
- [List Webhooks](https://docs.xerobi.com/sms-api/endpoint/list-webhooks.md)
- [Update webhook](https://docs.xerobi.com/sms-api/endpoint/update-webhook.md)
- [Create Webhook](https://docs.xerobi.com/certify/endpoint/create-webhook.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.