​

Webhooks

​

Event Types

​

How It Works

1. Register a webhook endpoint with a URL and the event types you want
2. When a matching event occurs, Oktivo sends a POST request to your URL
3. Your server processes the payload and returns a 200 response
4. If delivery fails, Oktivo retries with exponential backoff

​

Payload Structure

{
  "event": "call.analysis_ready",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "data": {
    "contactUID": "contact_abc123",
    "campaignUID": "campaign_xyz789",
    "phone": "+14155551234",
    "name": "John Doe",
    "agentId": "agent_def456",
    "callDuration": 145,
    "billingDuration": 180,
    "analysis": {
      "interested": true,
      "reason": "Wants to upgrade plan",
      "callback_time": "2025-01-16T14:00:00Z"
    }
  }
}

​

Agent Filtering

• Different CRMs handle different agents
• You want to route events to different processing pipelines
• Multiple teams share an Oktivo account

​

HMAC Signature Verification

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

​

Delivery & Retries

• Oktivo expects a 2xx response within 10 seconds
• Failed deliveries are retried up to 5 times with exponential backoff
• After all retries are exhausted, the endpoint is marked as failing
• You can view delivery logs in the dashboard

​

Best Practices

• Always verify the HMAC signature before processing
• Return 200 immediately, then process asynchronously
• Use idempotency keys (the contactUID + event type) to handle duplicate deliveries
• Set up agent filtering to keep webhook handlers focused