IllumiChat - AI-Powered Chat Platform

Webhooks let IllumiChat notify your systems in real time when events occur, such as a new chat message, a ticket being created, or a lead being captured. Instead of polling the API, your server receives an HTTP POST request for each event.

How Webhooks Work

Provide a URL and select the events you want to receive.

Events occur

When a subscribed event happens in IllumiChat, a payload is sent to your URL.

Your server processes the event

Your endpoint receives the POST request, verifies it, and takes action.

Setting Up a Webhook

Via the Dashboard

Go to Settings > Webhooks in your workspace
Click Create Webhook
Enter your endpoint URL (must be HTTPS)
Select the events you want to subscribe to
Save

Via the API

curl -X POST https://app.illumichat.com/api/webhooks \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/illumichat",
    "events": ["chat.message.created", "ticket.created", "lead.captured"],
    "active": true
  }'

Event Types

Event	Description
`chat.message.created`	A new message was sent in a conversation
`chat.session.created`	A new chat session started
`ticket.created`	A support ticket was created
`ticket.updated`	A ticket status or assignment changed
`lead.captured`	A lead was captured from the widget
`contact.created`	A new contact was added

Payload Format

Every webhook delivery includes a JSON payload with a consistent structure:

{
  "event": "ticket.created",
  "timestamp": "2025-06-15T14:30:00Z",
  "workspaceId": "ws_abc123",
  "data": {
    "id": "tkt_xyz789",
    "subject": "Cannot reset my password",
    "status": "open",
    "priority": "medium",
    "createdAt": "2025-06-15T14:30:00Z"
  }
}

Field	Type	Description
`event`	`string`	The event type
`timestamp`	`string`	ISO 8601 timestamp of when the event occurred
`workspaceId`	`string`	The workspace where the event originated
`data`	`object`	Event-specific payload

Handling Webhooks

Basic Express Server

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

app.use(express.json());

app.post("/webhooks/illumichat", (req, res) => {
  const { event, data } = req.body;

  switch (event) {
    case "ticket.created":
      console.log("New ticket:", data.subject);
      // Create a Jira issue, send a Slack notification, etc.
      break;

    case "lead.captured":
      console.log("New lead:", data.email);
      // Add to CRM, send welcome email, etc.
      break;

    case "chat.message.created":
      console.log("New message in session:", data.sessionId);
      break;

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

  // Always return 200 quickly to acknowledge receipt
  res.status(200).json({ received: true });
});

app.listen(3000);

Next.js API Route

// app/api/webhooks/illumichat/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(request: NextRequest) {
  const body = await request.json();
  const { event, data } = body;

  switch (event) {
    case "ticket.created":
      await handleNewTicket(data);
      break;
    case "lead.captured":
      await handleNewLead(data);
      break;
  }

  return NextResponse.json({ received: true });
}

async function handleNewTicket(data: any) {
  // Your ticket handling logic
}

async function handleNewLead(data: any) {
  // Your lead handling logic
}

Best Practices

Respond quickly

Return a 200 response as soon as possible. Process the event asynchronously if your logic takes more than a few seconds. IllumiChat may time out and retry if your endpoint does not respond promptly.

Handle duplicates

Webhook deliveries can occasionally be duplicated. Use the event timestamp and resource id to deduplicate on your end.

const processedEvents = new Set();

function handleWebhook(payload) {
  const key = `${payload.event}:${payload.data.id}:${payload.timestamp}`;
  if (processedEvents.has(key)) return;
  processedEvents.add(key);
  // Process the event
}

Use HTTPS

Webhook URLs must use HTTPS. For local development, use a tunneling service like ngrok to expose your local server.

ngrok http 3000
# Use the generated https://xxxx.ngrok.io/webhooks/illumichat URL

Log payloads during development

Log the full payload while building your integration so you can inspect the exact structure of each event type.

app.post("/webhooks/illumichat", (req, res) => {
  console.log(JSON.stringify(req.body, null, 2));
  res.status(200).json({ received: true });
});

Retry Policy

If your endpoint returns a non-2xx status code or times out, IllumiChat retries the delivery with exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes

After 3 failed retries, the delivery is marked as failed. You can view failed deliveries in your webhook settings and manually trigger a re-delivery.

Managing Webhooks

List Active Webhooks

curl https://app.illumichat.com/api/webhooks \
  -H "Authorization: Bearer <your-token>"

Disable a Webhook

curl -X PATCH https://app.illumichat.com/api/webhooks/{webhookId} \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

Delete a Webhook

curl -X DELETE https://app.illumichat.com/api/webhooks/{webhookId} \
  -H "Authorization: Bearer <your-token>"

Use webhooks together with the Contacts API and Tickets to build automated support workflows — for example, automatically creating a CRM record when a lead is captured and escalating to a human agent when a ticket is created.

Guides

Webhook Integration

How Webhooks Work

Setting Up a Webhook

Via the Dashboard

Via the API

Event Types

Payload Format

Handling Webhooks

Basic Express Server

Next.js API Route

Best Practices

Retry Policy

Managing Webhooks

List Active Webhooks

Disable a Webhook

Delete a Webhook

​How Webhooks Work

​Setting Up a Webhook

​Via the Dashboard

​Via the API

​Event Types

​Payload Format

​Handling Webhooks

​Basic Express Server

​Next.js API Route

​Best Practices

​Retry Policy

​Managing Webhooks

​List Active Webhooks

​Disable a Webhook

​Delete a Webhook

How Webhooks Work

Setting Up a Webhook

Via the Dashboard

Via the API

Event Types

Payload Format

Handling Webhooks

Basic Express Server

Next.js API Route

Best Practices

Retry Policy

Managing Webhooks

List Active Webhooks

Disable a Webhook

Delete a Webhook