Webhooks API

Webhooks allow you to receive real-time notifications about events in your Kaie workflows. Use webhooks to integrate with external systems, trigger custom actions, or build real-time dashboards.

Overview

Webhooks are HTTP callbacks that Kaie sends to your application when specific events occur. Common use cases include:

Notifying external systems of workflow completions
Triggering custom actions based on customer interactions
Building real-time monitoring dashboards
Integrating with third-party services

Webhook Events

Available Events

Event Type	Description	When Triggered
`workflow.started`	Workflow execution started	When a workflow begins execution
`workflow.completed`	Workflow execution completed	When a workflow finishes (success or failure)
`workflow.failed`	Workflow execution failed	When a workflow fails with an error
`message.received`	New message received	When a customer sends a message
`message.sent`	Message sent to customer	When a message is sent to a customer
`trigger.activated`	Trigger activated	When a trigger fires
`customer.created`	New customer created	When a new customer is added
`customer.updated`	Customer information updated	When customer data is modified

Event Payload Structure

All webhook events follow a consistent payload structure:

{
  "id": "event-123",
  "type": "workflow.completed",
  "timestamp": "2024-01-25T14:30:00Z",
  "data": {
    "workflow_id": "workflow-456",
    "execution_id": "execution-789",
    "status": "success",
    "duration_ms": 15000,
    "customer_id": "customer-123",
    "channel": "whatsapp"
  },
  "metadata": {
    "webhook_id": "webhook-abc",
    "retry_count": 0,
    "version": "1.0"
  }
}

Webhook Management

Create Webhook

Create a new webhook endpoint.

Request

POST /v1/webhooks

Request Body

{
  "name": "Customer Support Notifications",
  "url": "https://your-app.com/webhooks/kaie",
  "events": [
    "workflow.completed",
    "workflow.failed",
    "message.received"
  ],
  "secret": "your-webhook-secret",
  "active": true,
  "retry_policy": {
    "max_retries": 3,
    "retry_delay_ms": 1000
  }
}

Response

{
  "data": {
    "id": "webhook-123",
    "name": "Customer Support Notifications",
    "url": "https://your-app.com/webhooks/kaie",
    "events": [
      "workflow.completed",
      "workflow.failed",
      "message.received"
    ],
    "secret": "your-webhook-secret",
    "active": true,
    "created_at": "2024-01-25T14:30:00Z",
    "updated_at": "2024-01-25T14:30:00Z"
  }
}

List Webhooks

Retrieve all webhooks in your account.

Request

GET /v1/webhooks

Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20, max: 100)
`active`	boolean	Filter by active status
`event_type`	string	Filter by event type

Response

{
  "data": [
    {
      "id": "webhook-123",
      "name": "Customer Support Notifications",
      "url": "https://your-app.com/webhooks/kaie",
      "events": [
        "workflow.completed",
        "workflow.failed",
        "message.received"
      ],
      "active": true,
      "created_at": "2024-01-25T14:30:00Z",
      "updated_at": "2024-01-25T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5,
    "pages": 1
  }
}

Get Webhook

Retrieve details of a specific webhook.

Request

GET /v1/webhooks/{webhook_id}

Response

{
  "data": {
    "id": "webhook-123",
    "name": "Customer Support Notifications",
    "url": "https://your-app.com/webhooks/kaie",
    "events": [
      "workflow.completed",
      "workflow.failed",
      "message.received"
    ],
    "secret": "your-webhook-secret",
    "active": true,
    "retry_policy": {
      "max_retries": 3,
      "retry_delay_ms": 1000
    },
    "created_at": "2024-01-25T14:30:00Z",
    "updated_at": "2024-01-25T14:30:00Z"
  }
}

Update Webhook

Update an existing webhook.

Request

PUT /v1/webhooks/{webhook_id}

Request Body

{
  "name": "Updated Customer Support Notifications",
  "events": [
    "workflow.completed",
    "workflow.failed",
    "message.received",
    "customer.created"
  ],
  "retry_policy": {
    "max_retries": 5,
    "retry_delay_ms": 2000
  }
}

Response

{
  "data": {
    "id": "webhook-123",
    "name": "Updated Customer Support Notifications",
    "url": "https://your-app.com/webhooks/kaie",
    "events": [
      "workflow.completed",
      "workflow.failed",
      "message.received",
      "customer.created"
    ],
    "secret": "your-webhook-secret",
    "active": true,
    "retry_policy": {
      "max_retries": 5,
      "retry_delay_ms": 2000
    },
    "created_at": "2024-01-25T14:30:00Z",
    "updated_at": "2024-01-25T15:00:00Z"
  }
}

Delete Webhook

Delete a webhook permanently.

Request

DELETE /v1/webhooks/{webhook_id}

Response

{
  "message": "Webhook deleted successfully"
}

Webhook Security

Signature Verification

All webhook requests include an HMAC-SHA256 signature in the X-Kaie-Signature header for verification.

Verification Process

Extract the signature from the X-Kaie-Signature header
Create a hash of the request body using your webhook secret
Compare the signatures using a constant-time comparison

Example Implementation

const crypto = require('crypto');

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

// Usage
const signature = req.headers['x-kaie-signature'];
const isValid = verifyWebhookSignature(req.body, signature, webhookSecret);

Python Example

import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(signature, expected_signature)

# Usage
signature = request.headers.get('X-Kaie-Signature')
is_valid = verify_webhook_signature(request.body, signature, webhook_secret)

IP Whitelisting

For additional security, you can whitelist Kaie’s IP addresses:

203.0.113.0/24 - Primary webhook IP range
198.51.100.0/24 - Secondary webhook IP range

Webhook Delivery

Delivery Process

Event Occurs: An event triggers in your Kaie workflow
Webhook Queued: The webhook is added to the delivery queue
HTTP Request: Kaie sends a POST request to your endpoint
Response Handling: Your endpoint responds with HTTP status code
Retry Logic: If delivery fails, retry according to policy

Response Codes

Status Code	Behavior
`200 OK`	Webhook delivered successfully
`201 Created`	Webhook delivered successfully
`400 Bad Request`	Invalid request format (not retried)
`401 Unauthorized`	Authentication failed (not retried)
`403 Forbidden`	Access denied (not retried)
`404 Not Found`	Endpoint not found (not retried)
`429 Too Many Requests`	Rate limited (retried with backoff)
`500 Internal Server Error`	Server error (retried)
`502 Bad Gateway`	Gateway error (retried)
`503 Service Unavailable`	Service unavailable (retried)
`504 Gateway Timeout`	Gateway timeout (retried)

Retry Policy

Webhooks are retried according to the configured retry policy:

Max Retries: Maximum number of retry attempts (default: 3)
Retry Delay: Delay between retries in milliseconds (default: 1000)
Exponential Backoff: Delay increases exponentially with each retry
Max Delay: Maximum delay between retries (default: 30000ms)

Webhook Testing

Test Webhook

Test a webhook endpoint to verify it’s working correctly.

Request

POST /v1/webhooks/{webhook_id}/test

Request Body

{
  "event_type": "workflow.completed",
  "test_data": {
    "workflow_id": "test-workflow-123",
    "execution_id": "test-execution-456",
    "status": "success"
  }
}

Response

{
  "data": {
    "test_id": "test-789",
    "status": "success",
    "response_code": 200,
    "response_time_ms": 150,
    "tested_at": "2024-01-25T14:30:00Z"
  }
}

Webhook Logs

View delivery logs for a webhook.

Request

GET /v1/webhooks/{webhook_id}/logs

Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20, max: 100)
`status`	string	Filter by delivery status
`start_date`	string	Filter logs after this date
`end_date`	string	Filter logs before this date

Response

{
  "data": [
    {
      "id": "log-123",
      "webhook_id": "webhook-456",
      "event_type": "workflow.completed",
      "status": "success",
      "response_code": 200,
      "response_time_ms": 150,
      "attempt": 1,
      "delivered_at": "2024-01-25T14:30:00Z",
      "error_message": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "pages": 5
  }
}

Error Handling

Common Error Codes

Status Code	Error Code	Description
400	`INVALID_WEBHOOK_URL`	Webhook URL is invalid
400	`INVALID_EVENT_TYPES`	Event types are invalid
400	`INVALID_RETRY_POLICY`	Retry policy is invalid
404	`WEBHOOK_NOT_FOUND`	Webhook does not exist
409	`WEBHOOK_ALREADY_EXISTS`	Webhook with this URL already exists
422	`WEBHOOK_VALIDATION_FAILED`	Webhook validation failed

Error Response Format

{
  "error": {
    "code": "INVALID_WEBHOOK_URL",
    "message": "Webhook URL is invalid",
    "details": "URL must be a valid HTTPS endpoint",
    "field": "url"
  }
}

Best Practices

Webhook Implementation

Endpoint Design

Use HTTPS endpoints only
Implement idempotency for duplicate events
Respond quickly (within 5 seconds)
Use appropriate HTTP status codes

Security

Verify webhook signatures
Use IP whitelisting when possible
Implement rate limiting
Log all webhook deliveries

Performance Optimization

Processing

Process webhooks asynchronously
Use message queues for high volume
Implement proper error handling
Monitor webhook performance

Monitoring

Track delivery success rates
Monitor response times
Set up alerts for failures
Regular testing and validation

Next Steps

Explore more API endpoints:

Workflows API

Manage workflows programmatically

Triggers API

Manage workflow triggers

Analytics API

Access analytics data

Authentication

Learn about API authentication

​Webhooks API

​Overview

​Webhook Events

​Available Events

​Event Payload Structure

​Webhook Management

​Create Webhook

​Request

​Request Body

​Response

​List Webhooks

​Request

​Parameters

​Response

​Get Webhook

​Request

​Response

​Update Webhook

​Request

​Request Body

​Response

​Delete Webhook

​Request

​Response

​Webhook Security

​Signature Verification

​Verification Process

​Example Implementation

​Python Example

​IP Whitelisting

​Webhook Delivery

​Delivery Process

​Response Codes

​Retry Policy

​Webhook Testing

​Test Webhook

​Request

​Request Body

​Response

​Webhook Logs

​Request

​Parameters

​Response

​Error Handling

​Common Error Codes

​Error Response Format

​Best Practices

​Webhook Implementation

​Performance Optimization

​Next Steps

Workflows API

Triggers API

Analytics API

Authentication

Webhooks API

Overview

Webhook Events

Available Events

Event Payload Structure

Webhook Management

Create Webhook

Request

Request Body

Response

List Webhooks

Request

Parameters

Response

Get Webhook

Request

Response

Update Webhook

Request

Request Body

Response

Delete Webhook

Request

Response

Webhook Security

Signature Verification

Verification Process

Example Implementation

Python Example

IP Whitelisting

Webhook Delivery

Delivery Process

Response Codes

Retry Policy

Webhook Testing

Test Webhook

Request

Request Body

Response

Webhook Logs

Request

Parameters

Response

Error Handling

Common Error Codes

Error Response Format

Best Practices

Webhook Implementation

Performance Optimization

Next Steps