Developer Documentation
Everything you need to integrate Ithbat IAM into your applications
Webhooks
Receive real-time notifications about events in your system
Overview
Webhooks allow you to receive real-time HTTP notifications when events occur in your Ithbat IAM tenant. Set up webhook endpoints to be notified about user actions, security events, and system changes.
Webhooks are delivered via HTTP POST requests to the endpoint you configure. Your endpoint must return a 200 status code to acknowledge receipt.
Setting Up Webhooks
Create a webhook endpoint
Set up an HTTPS endpoint in your application to receive webhook events:
const express = require('express');
const app = express();
app.post('/webhooks/ithbat', express.json(), (req, res) => {
const event = req.body;
console.log('Received webhook:', event.type);
console.log('Event data:', event.data);
switch (event.type) {
case 'user.created':
handleUserCreated(event.data);
break;
case 'user.updated':
handleUserUpdated(event.data);
break;
case 'user.deleted':
handleUserDeleted(event.data);
break;
default:
console.log('Unhandled event type:', event.type);
}
res.status(200).json({ received: true });
});
app.listen(3000, () => {
console.log('Webhook endpoint listening on port 3000');
});Configure webhook in dashboard
Add your webhook URL in the Ithbat IAM dashboard and select which events you want to receive.
Webhook endpoints must use HTTPS for security. HTTP endpoints will be rejected.
Test your webhook
Use the webhook testing tool in the dashboard to send test events to your endpoint.
Event Types
user.createdUserTriggered when a new user is created
user.updatedUserTriggered when user information is updated
user.deletedUserTriggered when a user is deleted
user.loginSecurityTriggered when a user successfully logs in
user.mfa_enabledSecurityTriggered when a user enables MFA
tenant.updatedTenantTriggered when tenant settings are updated
Security & Verification
All webhook requests include a signature in the X-Ithbat-Signature header. Verify this signature to ensure the request came from Ithbat IAM:
Verifying Webhook Signatures
const crypto = require('crypto');
function verifyWebhookSignature(payload, signature, secret) {
const hmac = crypto.createHmac('sha256', secret);
const digest = hmac.update(JSON.stringify(payload)).digest('hex');
const expectedSignature = `sha256=${digest}`;
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}
app.post('/webhooks/ithbat', express.json(), (req, res) => {
const signature = req.headers['x-ithbat-signature'];
const webhookSecret = process.env.ITHBAT_WEBHOOK_SECRET;
if (!verifyWebhookSignature(req.body, signature, webhookSecret)) {
console.error('Invalid webhook signature');
return res.status(401).json({ error: 'Invalid signature' });
}
const event = req.body;
res.status(200).json({ received: true });
});Best Practices
Return 200 quickly
Acknowledge webhook receipt immediately with a 200 status code. Process the event asynchronously.
Verify signatures
Always verify the webhook signature before processing events to prevent unauthorized requests.
Handle duplicates
Webhooks may be delivered more than once. Use event IDs to track processed events and ignore duplicates.
Implement retry logic
If your endpoint is temporarily unavailable, we'll retry delivery. Implement idempotent processing.
Monitor webhook health
Set up monitoring and alerting for your webhook endpoint to ensure you don't miss important events.
Retry Policy
If your webhook endpoint returns a non-200 status code or times out, we'll retry delivery with exponential backoff:
Testing Webhooks
Use these tools to test your webhook integration during development: