🪝Webhooks

Overview

Wonderchat provides webhooks to notify your application in real-time when specific events occur within your chatbot. Webhooks are HTTP callbacks that send data to your specified endpoint when triggered.

Setting Up Webhooks

To create your first webhook:

  1. Navigate to https://app.wonderchat.io/settings?tab=integrations

  2. Scroll down to the Webhooks section

  3. Click on Connect & Manage

  4. Click on Add Webhook

  5. Enter your endpoint URL and select the event type you want to subscribe this URL to

  6. Enter a secret key (you will use this to verify the webhook on your backend)

  7. Save your webhook configuration

Once configured, Wonderchat will start sending HTTP POST requests to your endpoint whenever the selected events occur.

Authentication

All webhook requests include the following headers for security:

  • X-Wonderchat-Signature: HMAC-SHA256 signature of the payload using your webhook secret

  • X-Wonderchat-Timestamp: ISO 8601 timestamp of when the webhook was sent

  • Content-Type: application/json

Verifying Webhook Signatures

To verify that a webhook request is from Wonderchat, you will need to verify the secret that you entered in Step 6 when setting up your webhook:

const crypto = require("crypto");

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac("sha256", secret);
  hmac.update(JSON.stringify(payload));
  const expectedSignature = hmac.digest("hex");
  return signature === expectedSignature;
}

Webhook Events

1. LIVE_CHAT_INITIATED

Triggered when a user initiates a live chat session with a human agent.

Event Type: LIVE_CHAT_INITIATED

Payload Structure:

{
  "event": "LIVE_CHAT_INITIATED",
  "timestamp": "2023-10-15T14:30:00.000Z",
  "data": {
    "chatlogId": "clm1234567890abcdef",
    "userMessage": "I need help with my order",
    "email": "[email protected]",
    "name": "John Doe",
    "phoneNumber": "+1234567890",
    "chatbotId": "clm0987654321fedcba",
    "chatbotName": "Customer Support Bot"
  }
}

Field Descriptions:

  • chatlogId: Unique identifier for the chat conversation

  • userMessage: The message that triggered the live chat request

  • email: User's email address (optional, may be undefined)

  • name: User's name (optional, may be null)

  • phoneNumber: User's phone number (optional, may be null)

  • chatbotId: Unique identifier for the chatbot

  • chatbotName: Display name of the chatbot

Trigger Conditions:

  • User requests human support in regular chat

  • WhatsApp user requests human support when live chat is enabled

  • User sends their first message after live chat is initiated

2. USER_MESSAGE_SENT

Triggered when a user sends a message to the chatbot and receives a response. a Event Type: USER_MESSAGE_SENT

Payload Structure:

{
  "event": "USER_MESSAGE_SENT",
  "timestamp": "2023-10-15T14:35:00.000Z",
  "data": {
    "chatbotId": "clm0987654321fedcba",
    "chatbotName": "Customer Support Bot",
    "userMessage": "What are your business hours?",
    "chatbotResponse": "We're open Monday to Friday, 9 AM to 6 PM EST.",
    "chatlogId": "clm1234567890abcdef",
    "email": "[email protected]",
    "phoneNumber": "+1234567890",
    "name": "John Doe"
  }
}

Field Descriptions:

  • chatbotId: Unique identifier for the chatbot

  • chatbotName: Display name of the chatbot

  • userMessage: The message sent by the user

  • chatbotResponse: The response generated by the chatbot

  • chatlogId: Unique identifier for the chat conversation

  • email: User's email address (optional, only in main chat endpoint)

  • phoneNumber: User's phone number (optional, only in main chat endpoint)

  • name: User's name (optional, only in main chat endpoint)

Trigger Conditions:

  • User sends a message via the API (v1/chat endpoint)

  • User sends a message via the main chat interface

3. HUMAN_HANDOVER

Triggered when a conversation is handed over to a human agent via email.

Event Type: HUMAN_HANDOVER

Payload Structure:

{
  "event": "HUMAN_HANDOVER",
  "timestamp": "2023-10-15T14:40:00.000Z",
  "data": {
    "chatlogId": "clm1234567890abcdef",
    "chatbotId": "clm0987654321fedcba",
    "chatbotName": "Customer Support Bot",
    "userMessage": "I need to speak with a human about my complex issue",
    "email": "[email protected]",
    "name": "John Doe",
    "phoneNumber": "+1234567890",
    "supportEmail": "[email protected]",
    "escalationType": "EMAIL",
    "priority": "HIGH"
  }
}

Field Descriptions:

  • chatlogId: Unique identifier for the chat conversation

  • chatbotId: Unique identifier for the chatbot

  • chatbotName: Display name of the chatbot

  • userMessage: The message that triggered the handover request

  • email: User's email address (optional, may be undefined)

  • name: User's name (optional, may be null)

  • phoneNumber: User's phone number (optional, may be null)

  • supportEmail: The email address where the handover notification was sent

  • escalationType: Type of escalation (currently only "EMAIL" is supported)

  • priority: Ticket priority assigned by AI ("LOW", "MEDIUM", "HIGH", or null)

Trigger Conditions:

  • User requests human support through the email handover feature

  • User submits a message through the "Leave Email" functionality

  • Custom handover forms are submitted with collected field values

Error Handling

  • Webhook deliveries are attempted asynchronously

  • Failed deliveries are logged but do not affect the chat flow

  • Your endpoint should respond with a 2xx status code to indicate successful receipt

  • Non-2xx responses are considered failures

Testing Webhooks

You can test your webhook configuration through the Wonderchat dashboard. The test feature sends a sample payload to your endpoint to verify it's working correctly.

Requirements

  • Webhooks are available on Basic plans and above

  • Your endpoint must accept POST requests

  • Your endpoint must be publicly accessible via HTTPS

  • Response time should be under 10 seconds

Best Practices

  1. Verify signatures: Always verify the webhook signature to ensure requests are from Wonderchat

  2. Respond quickly: Return a 2xx response as soon as possible and process the webhook asynchronously

  3. Handle retries: Be prepared to handle duplicate webhook deliveries

  4. Log requests: Keep logs of received webhooks for debugging

  5. Use HTTPS: Always use HTTPS endpoints for security

Example Implementation

const express = require("express");
const crypto = require("crypto");

const app = express();
app.use(express.json());

app.post("/webhooks/wonderchat", (req, res) => {
  const signature = req.headers["x-wonderchat-signature"];
  const timestamp = req.headers["x-wonderchat-timestamp"];
  const secret = process.env.WONDERCHAT_WEBHOOK_SECRET;

  // Verify signature
  const hmac = crypto.createHmac("sha256", secret);
  hmac.update(JSON.stringify(req.body));
  const expectedSignature = hmac.digest("hex");

  if (signature !== expectedSignature) {
    return res.status(401).send("Invalid signature");
  }

  // Process webhook based on event type
  const { event, data } = req.body;

  switch (event) {
    case "LIVE_CHAT_INITIATED":
      // Handle live chat initiation
      console.log("Live chat started:", data);
      break;

    case "USER_MESSAGE_SENT":
      // Handle user message
      console.log("User message:", data);
      break;

    case "HUMAN_HANDOVER":
      // Handle human handover
      console.log("Human handover requested:", data);
      // Send notification to support team
      // Create ticket in help desk system
      // Update internal dashboards
      break;

    default:
      console.log("Unknown event type:", event);
  }

  // Respond immediately
  res.status(200).send("OK");
});
PreviousClient SDKNextChatbot Technical FAQ

Last updated

Was this helpful?