Webhooks

​

Overview

​

How webhooks work

1. Configure a webhook URL in your business integrations
2. When an event occurs, Iqra AI sends an HTTP POST request to your URL
3. Your server processes the event and responds with a 200 status code
4. If delivery fails, Iqra AI retries with exponential backoff

​

Setting up webhooks

​

Create a webhook integration

1. Navigate to your business in the Iqra AI dashboard
2. Go to Settings > Integrations
3. Click “Add Integration” and select “Webhook”
4. Configure the following:

​

Configure event subscriptions

• call.initiated - Outbound call has been queued
• call.started - Call connection established
• call.completed - Call has ended
• call.failed - Call could not be completed
• conversation.started - Conversation session began
• conversation.message - New message in conversation
• conversation.ended - Conversation session completed
• agent.joined - AI agent joined conversation
• agent.left - AI agent left conversation

​

Webhook payload structure

{
  "EventType": "call.completed",
  "EventId": "evt_abc123xyz789",
  "Timestamp": "2024-01-15T14:35:30Z",
  "BusinessId": 12345,
  "Data": {
    // Event-specific data
  }
}

​

Event types and payloads

​

call.completed

{
  "EventType": "call.completed",
  "EventId": "evt_abc123",
  "Timestamp": "2024-01-15T14:35:30Z",
  "BusinessId": 12345,
  "Data": {
    "QueueId": "queue_xyz789",
    "SessionId": "session_abc123",
    "RecipientNumber": "+1234567890",
    "Status": "Completed",
    "Duration": 330,
    "EndType": "Normal",
    "CampaignId": "campaign_001",
    "Metadata": {
      "CustomField": "value"
    }
  }
}

​

conversation.ended

{
  "EventType": "conversation.ended",
  "EventId": "evt_def456",
  "Timestamp": "2024-01-15T14:35:30Z",
  "BusinessId": 12345,
  "Data": {
    "SessionId": "session_abc123",
    "QueueId": "queue_xyz789",
    "StartTime": "2024-01-15T14:30:00Z",
    "EndTime": "2024-01-15T14:35:30Z",
    "Duration": 330,
    "MessageCount": 12,
    "EndType": "Normal",
    "Summary": "Customer inquiry about pricing"
  }
}

​

conversation.message

{
  "EventType": "conversation.message",
  "EventId": "evt_ghi789",
  "Timestamp": "2024-01-15T14:30:05Z",
  "BusinessId": 12345,
  "Data": {
    "SessionId": "session_abc123",
    "SenderId": "client_123",
    "Role": "User",
    "Content": "I'd like to know more about your pricing.",
    "Timestamp": "2024-01-15T14:30:05Z"
  }
}

​

Securing webhooks

​

Verify signatures

X-Iqra-Signature: sha256=abc123...

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = 'sha256=' + hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

​

Validate event IDs

const processedEvents = new Set();

function handleWebhook(event) {
  if (processedEvents.has(event.EventId)) {
    console.log('Duplicate event, skipping');
    return;
  }
  
  processedEvents.add(event.EventId);
  // Process event...
}

​

Responding to webhooks

1. Respond quickly (within 5 seconds)
2. Return HTTP 200 status code
3. Process the event asynchronously if needed

app.post('/webhooks/iqra', async (req, res) => {
  // Respond immediately
  res.status(200).send('OK');
  
  // Process asynchronously
  processWebhookAsync(req.body).catch(console.error);
});

​

Retry behavior

• First retry: after 1 minute
• Second retry: after 5 minutes
• Third retry: after 15 minutes
• Fourth retry: after 1 hour
• Fifth retry: after 6 hours

​

Testing webhooks

​

Use webhook testing tools

• webhook.site - Inspect webhook payloads
• ngrok - Expose local server for testing
• requestbin - Collect and examine webhooks

​

Trigger test events

1. Go to Integrations > Your Webhook
2. Click “Send Test Event”
3. Select event type and review the payload
4. Send to your endpoint

​

Best practices

​

Endpoint design

• Use HTTPS for security
• Implement signature verification
• Return 200 quickly, process asynchronously
• Handle duplicate events gracefully
• Log all webhook activity

​

Error handling

• Don’t fail on unknown event types (for forward compatibility)
• Validate payload structure before processing
• Store failed events for manual review
• Alert on repeated webhook failures

​

Performance

• Process webhooks in a queue
• Scale webhook handlers independently
• Monitor processing latency
• Set up dead letter queues for failures

​

Security

• Whitelist Iqra AI IP addresses if possible
• Verify webhook signatures
• Don’t expose sensitive data in logs
• Rotate signing secrets periodically

​

Monitoring webhooks

• Delivery success/failure rates
• Recent webhook deliveries and responses
• Retry attempts and outcomes
• Event type distribution

​

Common issues

​

Webhooks not being received

• Verify your endpoint URL is correct and accessible
• Check that your server is responding with 200
• Ensure your firewall allows Iqra AI’s IP addresses
• Review webhook logs in the dashboard

​

Duplicate events

• This is normal due to retry logic
• Implement idempotency using EventId
• Store processed event IDs

​

Timeout errors

• Your endpoint must respond within 5 seconds
• Process events asynchronously
• Return 200 immediately

​

Reference

​

Integration object structure

{
  "Id": "integration_abc123",
  "Type": "webhook",
  "FriendlyName": "Production Webhook",
  "Fields": {
    "Url": "https://api.yourapp.com/webhooks/iqra",
    "Events": [
      "call.completed",
      "conversation.ended"
    ]
  },
  "EncryptedFields": {
    "Secret": "[encrypted]"
  }
}