Skip to main content
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

1

Register a webhook

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

Events occur

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

Your server processes the event

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

​
Setting Up a Webhook

​
Via the Dashboard

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

​
Via the API

curl -X POST https://beta.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

EventDescription
chat.message.createdA new message was sent in a conversation
chat.session.createdA new chat session started
ticket.createdA support ticket was created
ticket.updatedA ticket status or assignment changed
lead.capturedA lead was captured from the widget
contact.createdA 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"
  }
}
FieldTypeDescription
eventstringThe event type
timestampstringISO 8601 timestamp of when the event occurred
workspaceIdstringThe workspace where the event originated
dataobjectEvent-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

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.
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
}
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 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:
AttemptDelay
1st retry1 minute
2nd retry5 minutes
3rd retry30 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://beta.illumichat.com/api/webhooks \
  -H "Authorization: Bearer <your-token>"

​
Disable a Webhook

curl -X PATCH https://beta.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://beta.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.