API Reference

Webhooks

Receive real-time event notifications when conversations, tickets, or contacts change.

7 min read Updated July 2026

Webhooks let you subscribe to Liya events and receive HTTP POST notifications to a URL you control. Use webhooks to sync data with your CRM, trigger workflows in Zapier or n8n, send Slack notifications, or build custom integrations without polling the API.

Available events

Event	Fires when
conversation.created	A new conversation is created
conversation.assigned	A conversation is assigned to an agent or group
conversation.resolved	A conversation is marked as resolved
conversation.reopened	A resolved conversation receives a new customer message
conversation.escalated	An escalation trigger fires on a conversation
message.created	Any new message is added (customer or agent)
message.sent	An agent sends a reply to the customer
ai_draft.generated	A new AI draft is generated for a conversation
contact.created	A new contact is created
contact.updated	A contact's attributes are updated
csat.submitted	A customer submits a CSAT rating
sla.first_response_breached	First response SLA deadline is missed
sla.resolution_breached	Resolution SLA deadline is missed
knowledge.gap_detected	A new knowledge gap cluster is identified

Setting up a webhook

Go to Settings → Integrations → Webhooks

Click Add endpoint.

Enter your endpoint URL

Enter the HTTPS URL that will receive webhook events. Liya does not support HTTP endpoints — your URL must use HTTPS with a valid certificate.

Select events to subscribe to

Choose which event types to receive. We recommend subscribing only to events you need to reduce processing overhead on your server.

Copy your signing secret

After creating the endpoint, copy the Signing secret. Store it securely — you'll use it to verify webhook authenticity (see below).

Test the endpoint

Click Send test event to send a sample payload to your endpoint. Your endpoint should respond with HTTP 200. Any other response (or a timeout after 10 seconds) is treated as a failure.

Webhook payload format

json

{
  "id": "evt_01JABC123",
  "type": "conversation.created",
  "created_at": "2026-07-03T14:22:00Z",
  "workspace_id": "ws_a1b2c3d4e5f6",
  "data": {
    "conversation": {
      "id": "conv_01JABCDEF",
      "status": "open",
      "priority": "high",
      "channel": "email",
      "contact": { "id": "cnt_01JXYZ789", "email": "[email protected]" },
      "ai": { "intent": "billing_issue", "urgency": "high", "confidence": 87 },
      "created_at": "2026-07-03T14:22:00Z"
    }
  }
}

Verifying webhook signatures

Every webhook request includes an X-Liya-Signatureheader containing an HMAC-SHA256 signature of the raw request body, signed with your endpoint's secret. Always verify this signature before processing the event.

javascript

const crypto = require("crypto");

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

// In your webhook handler:
app.post("/webhooks/liya", (req, res) => {
  const signature = req.headers["x-liya-signature"];
  const rawBody   = req.rawBody; // raw Buffer/string before JSON parsing

  if (!verifyWebhookSignature(rawBody, signature, process.env.LIYA_WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }

  const event = req.body;
  // Handle the event...
  res.status(200).send("OK");
});

Never skip signature verification in production. Without it, anyone who discovers your webhook URL can send fraudulent events to your system.

Retry behaviour

If your endpoint returns a non-200 status or times out, Liya retries the event using exponential backoff:

Attempt	Delay after previous failure
1st retry	5 seconds
2nd retry	30 seconds
3rd retry	5 minutes
4th retry	30 minutes
5th retry	2 hours
6th retry	5 hours (final)

After 6 failed attempts, the event is marked as failed and no further retries are attempted. Failed events can be replayed from the webhook log in Settings → Integrations → Webhooks → [endpoint] → Logs.

Idempotency

Due to retries, your endpoint may receive the same event more than once. Each event has a unique id field. Store processed event IDs and skip duplicate deliveries to ensure idempotent processing.

PreviousKnowledge API

Next Rate limits