Webhooks Documentation

https://api.example.com/webhooks
https://myapp.example.com/chatbot-events
https://webhook.example.com/notifications

sha256=3d5a2c8f9e1b4a6d7c8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c

X-Webhook-Signature: sha256=abc123...
X-Webhook-Event: message.received
X-Webhook-Delivery-Id: del_a1b2c3d4e5f6
X-Webhook-Timestamp: 1729180800
User-Agent: SolidScale-Webhook/1.0
Content-Type: application/json

{
  "event": "message.received",
  "eventId": "evt_a1b2c3d4e5f6789",
  "timestamp": "2025-10-21T14:30:00.000Z",
  "chatbotId": 1,
  "chatbotName": "Customer Support Bot",
  "userId": 42,
  "data": {
    // Event-specific data here
    // Structure varies by event type
  }
}

{
  "challenge": "abc123-challenge-token-xyz789"
}

app.post('/webhooks', async (req, res) => {
  // 1. Verify signature first
  if (!verifySignature(req)) {
    return res.status(401).send('Invalid signature');
  }
  
  // 2. Respond immediately
  res.status(200).send('OK');
  
  // 3. Process asynchronously
  await queueWebhookForProcessing(req.body);
});

{
  "event": "conversation.started",
  "eventId": "evt_a1b2c3d4e5f6789",
  "timestamp": "2025-10-21T14:30:00.000Z",
  "chatbotId": 1,
  "chatbotName": "Customer Support Bot",
  "userId": 42,
  "data": {
    "message": "Hi, I need help with my order",
    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
    "chatbotId": 1,
    "startedAt": "2025-10-21T14:30:00.000Z"
  }
}

{
  "event": "message.received",
  "eventId": "evt_b2c3d4e5f6a7890",
  "timestamp": "2025-10-21T14:31:15.000Z",
  "chatbotId": 1,
  "chatbotName": "Customer Support Bot",
  "userId": 42,
  "data": {
    "message": "What's the status of order #12345?",
    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
    "chatbotId": 1,
    "timestamp": "2025-10-21T14:31:15.000Z"
  }
}

{
  "event": "message.sent",
  "eventId": "evt_c3d4e5f6a7b8901",
  "timestamp": "2025-10-21T14:31:18.000Z",
  "chatbotId": 1,
  "chatbotName": "Customer Support Bot",
  "userId": 42,
  "data": {
    "response": "Let me check the status of order #12345 for you. Your order was shipped on October 20th and should arrive by October 23rd. The tracking number is 1Z999AA1234567890.",
    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
    "chatbotId": 1,
    "responseTimeMs": 1247,
    "timestamp": "2025-10-21T14:31:18.000Z"
  }
}

{
  "event": "knowledge.added",
  "eventId": "evt_d4e5f6a7b8c9012",
  "timestamp": "2025-10-21T15:00:00.000Z",
  "chatbotId": 0,
  "chatbotName": null,
  "userId": 42,
  "data": {
    "message": "A new document has been uploaded as a knowledge source.",
    "knowledgeSource": {
      "id": 123,
      "name": "Product Documentation Q4 2024",
      "type": "document",
      "sourceUrl": null,
      "fileName": "product-docs-q4-2024.pdf",
      "fileSize": 2458624,
      "fileType": "application/pdf",
      "status": "active",
      "lastProcessedAt": "2025-10-21T15:00:05.000Z",
      "createdAt": "2025-10-21T15:00:00.000Z",
      "updatedAt": "2025-10-21T15:00:00.000Z",
      "usedByChatbotsCount": 0,
      "uploadedBy": 42
    }
  }
}

{
  "event": "knowledge.added",
  "eventId": "evt_e5f6a7b8c9d0123",
  "timestamp": "2025-10-21T15:15:00.000Z",
  "chatbotId": 0,
  "chatbotName": null,
  "userId": 42,
  "data": {
    "message": "A new knowledge source has been added.",
    "knowledgeSource": {
      "id": 124,
      "name": "FAQ Page",
      "type": "url",
      "sourceUrl": "https://example.com/faq",
      "fileName": null,
      "fileSize": null,
      "fileType": null,
      "createdAt": "2025-10-21T15:15:00.000Z",
      "createdBy": 42
    }
  }
}

{
  "event": "knowledge.deleted",
  "eventId": "evt_f6a7b8c9d0e1234",
  "timestamp": "2025-10-21T16:00:00.000Z",
  "chatbotId": 0,
  "chatbotName": null,
  "userId": 42,
  "data": {
    "message": "A knowledge source has been deleted.",
    "knowledgeSource": {
      "id": 123,
      "deletedBy": 42,
      "deletedAt": "2025-10-21T16:00:00.000Z"
    }
  }
}

{
  "event": "human.handoff.requested",
  "eventId": "evt_g7b8c9d0e1f2345",
  "timestamp": "2025-10-21T14:35:00.000Z",
  "chatbotId": 1,
  "chatbotName": "Customer Support Bot",
  "userId": 42,
  "data": {
    "interactionId": 5678,
    "message": "I need to speak with someone about canceling my subscription",
    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
    "chatbotId": 1,
    "userId": 42,
    "timestamp": "2025-10-21T14:35:00.000Z",
    "conversationContext": [
      {
        "userMessage": "Hi, I need help with my subscription",
        "botResponse": "I'd be happy to help with your subscription. What would you like to know?",
        "timestamp": "2025-10-21T14:30:00.000Z"
      },
      {
        "userMessage": "How do I cancel it?",
        "botResponse": "You can cancel your subscription by going to Settings > Subscription > Cancel. Would you like me to guide you through it?",
        "timestamp": "2025-10-21T14:32:00.000Z"
      },
      {
        "userMessage": "I tried that but I'm having issues",
        "botResponse": "I understand you're having difficulties. Let me help you troubleshoot...",
        "timestamp": "2025-10-21T14:33:00.000Z"
      },
      {
        "userMessage": "This isn't working. Can I talk to a real person?",
        "botResponse": null,
        "timestamp": "2025-10-21T14:34:30.000Z"
      }
    ]
  }
}

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secretKey) {
  // Generate expected signature
  const expectedSignature = 'sha256=' + 
    crypto
      .createHmac('sha256', secretKey)
      .update(JSON.stringify(payload))
      .digest('hex');
  
// Use timing-safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// Example usage in Express
app.post('/webhooks', express.json(), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const secretKey = process.env.WEBHOOK_SECRET_KEY;
  
  if (!verifyWebhookSignature(req.body, signature, secretKey)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // Signature is valid - respond immediately
  res.status(200).send('OK');
  
  // Process webhook asynchronously
  processWebhook(req.body);
});

import hmac
import hashlib
import json

def verify_webhook_signature(payload, signature, secret_key):
    """Verify the webhook signature"""
    
    # Generate expected signature
    payload_json = json.dumps(payload, separators=(',', ':'))
    expected_signature = 'sha256=' + hmac.new(
        secret_key.encode('utf-8'),
        payload_json.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    # Use constant-time comparison
    return hmac.compare_digest(signature, expected_signature)

# Example usage in Flask
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhooks', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Webhook-Signature')
    secret_key = os.getenv('WEBHOOK_SECRET_KEY')
    
    if not verify_webhook_signature(request.json, signature, secret_key):
        return jsonify({'error': 'Invalid signature'}), 401
    
    # Signature is valid
    # Process webhook asynchronously here
    
    return 'OK', 200

using System;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

public class WebhookVerifier
{
    public static bool VerifyWebhookSignature(
        object payload, 
        string signature, 
        string secretKey)
    {
        // Serialize payload to JSON
        var payloadJson = JsonSerializer.Serialize(payload);
        var payloadBytes = Encoding.UTF8.GetBytes(payloadJson);
        var keyBytes = Encoding.UTF8.GetBytes(secretKey);
        
        // Generate expected signature
        using var hmac = new HMACSHA256(keyBytes);
        var hashBytes = hmac.ComputeHash(payloadBytes);
        var expectedSignature = "sha256=" + 
            BitConverter.ToString(hashBytes)
                .Replace("-", "")
                .ToLower();
        
        // Constant-time comparison
        return CryptographicEquals(signature, expectedSignature);
    }
    
    private static bool CryptographicEquals(string a, string b)
    {
        if (a == null || b == null || a.Length != b.Length)
            return false;
        
        var result = 0;
        for (var i = 0; i < a.Length; i++)
        {
            result |= a[i] ^ b[i];
        }
        
        return result == 0;
    }
}

// Example usage in ASP.NET Core
[ApiController]
[Route("api/webhooks")]
public class WebhookController : ControllerBase
{
    [HttpPost]
    public IActionResult HandleWebhook([FromBody] JsonElement payload)
    {
        var signature = Request.Headers["X-Webhook-Signature"];
        var secretKey = Environment.GetEnvironmentVariable("WEBHOOK_SECRET_KEY");
        
        if (!WebhookVerifier.VerifyWebhookSignature(payload, signature, secretKey))
        {
            return Unauthorized(new { error = "Invalid signature" });
        }
        
        // Process webhook asynchronously
        _ = ProcessWebhookAsync(payload);
        
        return Ok("OK");
    }
}

<?php

function verifyWebhookSignature($payload, $signature, $secretKey) {
    // Generate expected signature
    $payloadJson = json_encode($payload);
    $expectedSignature = 'sha256=' . hash_hmac('sha256', $payloadJson, $secretKey);
    
    // Use timing-safe comparison
    return hash_equals($signature, $expectedSignature);
}

// Example usage
$payload = json_decode(file_get_contents('php://input'), true);
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];
$secretKey = getenv('WEBHOOK_SECRET_KEY');

if (!verifyWebhookSignature($payload, $signature, $secretKey)) {
    http_response_code(401);
    echo json_encode(['error' => 'Invalid signature']);
    exit;
}

// Signature is valid - respond immediately
http_response_code(200);
echo 'OK';

// Process webhook asynchronously
processWebhook($payload);
?>

function validateWebhookTimestamp(timestampHeader) {
  const webhookTimestamp = parseInt(timestampHeader);
  const currentTimestamp = Math.floor(Date.now() / 1000);
  
  // Reject webhooks older than 5 minutes
  const MAX_AGE_SECONDS = 5 * 60;
  const age = currentTimestamp - webhookTimestamp;
  
  if (age > MAX_AGE_SECONDS) {
    return false; // Webhook too old
  }
  
  if (age < -60) {
    return false; // Webhook timestamp is in the future (clock skew)
  }
  
  return true;
}

// Example usage
app.post('/webhooks', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
  
  // Validate timestamp first
  if (!validateWebhookTimestamp(timestamp)) {
    return res.status(401).json({ error: 'Webhook timestamp invalid or too old' });
  }
  
  // Then verify signature
  if (!verifyWebhookSignature(req.body, signature, secretKey)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  res.status(200).send('OK');
  processWebhook(req.body);
});

const processedEvents = new Set(); // Use Redis in production

async function processWebhook(payload) {
  const eventId = payload.eventId;
  
  // Check if we've already processed this event
  if (processedEvents.has(eventId)) {
    console.log(`Duplicate event ${eventId} ignored`);
    return;
  }
  
  // Process the webhook
  try {
    await handleWebhookEvent(payload);
    
    // Mark as processed (with TTL in production)
    processedEvents.add(eventId);
    
    // In production, use Redis with expiration:
    // await redis.setex(`processed:${eventId}`, 86400, '1'); // 24h TTL
    
  } catch (error) {
    console.error(`Error processing event ${eventId}:`, error);
    // Don't mark as processed if there was an error
    throw error;
  }
}

// Example with Redis
const Redis = require('ioredis');
const redis = new Redis();

async function processWebhookWithRedis(payload) {
  const eventId = payload.eventId;
  const lockKey = `webhook:processing:${eventId}`;
  
  // Try to acquire lock (prevents concurrent processing)
  const acquired = await redis.set(lockKey, '1', 'EX', 3600, 'NX');
  
  if (!acquired) {
    console.log(`Event ${eventId} already being processed`);
    return;
  }
  
  try {
    await handleWebhookEvent(payload);
  } finally {
    // Release lock after processing
    await redis.del(lockKey);
  }
}

{
  "event": "webhook.test",
  "eventId": "evt_test123abc",
  "timestamp": "2025-10-21T10:30:00.000Z",
  "chatbotId": 1,
  "chatbotName": "Test Chatbot",
  "userId": 42,
  "data": {
    "message": "This is a test webhook event",
    "testTimestamp": "2025-10-21T10:30:00.000Z"
  }
}