CallCall.ai

Webhooks

CallCall.ai uses webhooks to notify your application when events happen in real-time. This guide explains how to implement, secure, and manage webhooks effectively.

Available Events

customer.qualified

Triggered when a customer meets qualification criteria

service.matched

Triggered when services are matched to a customer

message.received

Triggered when a new message is received

analysis.completed

Triggered when business analysis is complete

Event Payload

{
  "id": "evt_123456789",
  "type": "customer.qualified",
  "created": "2025-02-07T02:55:00Z",
  "data": {
    "customer_id": "customer_987654321",
    "score": 85,
    "qualification_type": "hot",
    "triggers": ["budget_match", "high_engagement"]
  },
  "version": "2024-01-01"
}

Implementation Guide

1. Register Endpoint

POST /api/v1/webhooks
{
  "url": "https://your-domain.com/webhook",
  "events": ["customer.qualified", "service.matched"],
  "description": "Production webhook handler"
}

2. Verify Signatures

const signature = req.headers['x-callcall-signature'];
const timestamp = req.headers['x-callcall-timestamp'];
const payload = req.body;

const isValid = verifyWebhookSignature(
  payload,
  signature,
  timestamp,
  WEBHOOK_SECRET
);

3. Handle Events

app.post('/webhook', async (req, res) => {
  const event = req.body;
  
  switch(event.type) {
    case 'customer.qualified':
      await handleQualifiedCustomer(event.data);
      break;
    case 'service.matched':
      await handleServiceMatch(event.data);
      break;
    default:
      console.log(`Unhandled event: ${event.type}`);
  }

  res.json({ received: true });
});

4. Implement Retry Logic

// Exponential backoff
const retryWebhook = async (event, attempt = 1) => {
  try {
    await processWebhook(event);
  } catch (error) {
    if (attempt <= 5) {
      const delay = Math.pow(2, attempt) * 1000;
      await wait(delay);
      return retryWebhook(event, attempt + 1);
    }
    throw error;
  }
};

Security Best Practices

  • •Always verify webhook signatures
  • •Use HTTPS endpoints only
  • •Implement request timeouts
  • •Rotate webhook secrets regularly

Monitoring

  • •Track delivery success rates
  • •Monitor response times
  • •Set up failure alerts
  • •Log all webhook activities

Troubleshooting

  • •Check webhook logs
  • •Verify endpoint availability
  • •Test with webhook simulator
  • •Review response codes

Testing Tools

Webhook Tester

Test your webhook endpoints with sample events

Event Viewer

View and filter webhook delivery history

Signature Validator

Verify webhook signature implementation

Debug Console

Debug webhook delivery issues in real-time