Real-time Events

Webhooks

Receive real-time notifications when events happen in your KhaleejiAPI account.

Overview

Webhooks allow you to receive HTTP POST requests to your server whenever certain events occur. This is useful for batch processing results, usage alerts, and integrating with your existing workflows.

Setting Up Webhooks

  1. Go to your Dashboard → Settings → Webhooks
  2. Click Add Endpoint
  3. Enter your webhook URL (must be HTTPS)
  4. Select the events you want to receive
  5. Save and copy your webhook signing secret

Webhook Payload

All webhook payloads follow a consistent structure:

json
1{
2  "id": "evt_1234567890",
3  "type": "validation.completed",
4  "created": 1705312800,
5  "data": {
6    "api": "email-validation",
7    "request_id": "req_abc123",
8    "result": {
9      "email": "user@example.com",
10      "is_valid": true,
11      "deliverability": "DELIVERABLE"
12    }
13  }
14}

Event Types

Event TypeDescription
validation.completedEmail or phone validation completed
lookup.completedIP or company lookup completed
batch.startedBatch processing has started
batch.completedBatch processing completed
batch.failedBatch processing failed
usage.thresholdUsage threshold reached (80%, 90%, 100%)

Verifying Signatures

Every webhook request includes an X-Khaleeji-Signature header containing an HMAC-SHA256 signature. Always verify this signature to ensure the request is from KhaleejiAPI.

javascript
1import crypto from 'crypto';
2 
3function verifyWebhookSignature(
4  payload: string,
5  signature: string,
6  secret: string
7): boolean {
8  const expectedSignature = crypto
9    .createHmac('sha256', secret)
10    .update(payload)
11    .digest('hex');
12  
13  return crypto.timingSafeEqual(
14    Buffer.from(signature),
15    Buffer.from(expectedSignature)
16  );
17}
18 
19// In your webhook handler
20app.post('/webhooks/khaleeji', (req, res) => {
21  const signature = req.headers['x-khaleeji-signature'];
22  const isValid = verifyWebhookSignature(
23    JSON.stringify(req.body),
24    signature,
25    process.env.WEBHOOK_SECRET
26  );
27 
28  if (!isValid) {
29    return res.status(401).json({ error: 'Invalid signature' });
30  }
31 
32  // Process the webhook
33  const event = req.body;
34  console.log('Received event:', event.type);
35  
36  res.status(200).json({ received: true });
37});

Retry Policy

If your endpoint returns a non-2xx status code or times out (30 seconds), we will retry the webhook with exponential backoff:

Attempt 1

Immediate

Attempt 2

1 minute

Attempt 3

5 minutes

Attempt 4

30 minutes

Attempt 5

2 hours

After 5 failed attempts, the webhook will be marked as failed. You can view failed webhooks and manually retry them from your dashboard.

Best Practices

Respond quickly

Return a 200 response immediately and process the webhook asynchronously.

Handle duplicates

Use the event ID to deduplicate webhooks. We may send the same event multiple times.

Verify signatures

Always verify the webhook signature before processing to prevent spoofing.

Use HTTPS

Webhook endpoints must use HTTPS. We do not support HTTP endpoints.