Send Escalation Events to a Webhook

Webhooks let qlar notify your systems in near real time when escalation events happen, for example to:

• Create or update tickets in your helpdesk tool
• Notify a Slack or Teams channel
• Trigger internal monitoring or compliance workflows

In the example, Kirana Group sends Atlas's escalation events to its internal endpoint https://hooks.kirana.example/qlar/escalations, which posts each new case to the operations duty channel.

Before you start

• Escalation is enabled and saved. See Configure Escalation.
• You have tested the supervisor flow once. See Receive and Manage Escalations.
• You have an HTTPS endpoint, reachable from the internet, that can receive test requests and show you their body.

Step 1: Open the Webhook Notifications card

In the CMS, go to Conversation → Escalation and scroll to Webhook Notifications. It sits on the same page as the other escalation settings and is saved with the same Save button.

Step 2: Enable the webhook

Turn the switch on. The label changes to Enabled: "Receive HTTP POST notifications when escalation events occur (created, claimed, completed, released)." The Webhook URL and Secret Key fields appear.

Step 3: Set the webhook URL

Enter your endpoint in Webhook URL. It is required while the webhook is enabled and must start with https://, as the hint under the field says. For Kirana:

https://hooks.kirana.example/qlar/escalations

Use an endpoint that is reachable from the internet (not localhost), and check your server or API gateway logs to confirm that requests to this path are accepted.

The Secret Key box still says (not yet generated — save first). The key is created when you save.

Step 4: Save, then copy the secret key

1. Click Save at the bottom of the Escalation page. A message confirms Escalation settings saved successfully.
2. The Secret Key box now holds the generated key. Click the copy button at its right end and store the key in your backend's secret store (for example an environment secret or a vault), not in source control.

The card explains what the key is for: "Include this key in your webhook handler to verify requests originate from this platform."

Do not put the key in frontend code or public logs, and mask it in dashboards.

Saving puts your agent in draft. Escalations in the Preview use the webhook right away; escalations from the live agent use it only after you click Publish (see Preview and Publish Changes).

Step 5: Regenerate the key if needed

If a key may have leaked, click Regenerate Key. The CMS confirms A new webhook secret key has been generated. Copy the new key, update your receiver, then save and publish so the live agent uses it too. Requests with the old key should now be rejected by your receiver.

Step 6: Read the API documentation

Click Show API Documentation under the card. The Webhook API Documentation panel has three tabs:

• Overview: how delivery works and the event types.
• Payload: the secret key, an example payload, and the field reference.
• Code Examples: a small receiver in Node.js, C#, Python and Java.

Hide API Documentation collapses the panel again.

Step 7: Understand the event types

Each request carries one event in eventType:

The card's description names the four main events (created, claimed, completed, released). The API documentation also lists escalation.updated. Route your logic by eventType, handle all five, and log and skip any value you do not recognize instead of failing.

Step 8: Check the payload

Each event is a JSON POST. This example shows the Atlas case from the previous tutorials:

{
  "secret": "your-webhook-secret-key",
  "eventType": "escalation.created",
  "timestamp": "2026-10-04T18:29:00.000Z",
  "data": {
    "escalationId": "b75f06a1-...",
    "agentId": "YOUR_AGENT_ID",
    "agentName": "Atlas",
    "threadId": "thread-...",
    "status": "Pending",
    "topic": "Approval limits",
    "area": "Kirana Group",
    "triggerCondition": "Decision outside the SOPs",
    "urgencyLevel": "high",
    "reason": "User requests an exception to approve a USD 1.2 million project themselves because the Regional Director is on leave and vendor deadline is tomorrow.",
    "endUser": {
      "userId": "...",
      "displayName": "Rina Wijaya",
      "email": "rina.wijaya@kirana.example",
      "phoneNumber": "6281200000000"
    },
    "supervisor": null,
    "resolutionNote": null,
    "createdAt": "2026-10-04T18:29:00.000Z",
    "updatedAt": "2026-10-04T18:29:00.000Z",
    "completedAt": null
  }
}

• supervisor is filled in once someone claims the case, and resolutionNote and completedAt with escalation.completed.
• urgencyLevel is one of low, medium, high, critical.
• The Payload tab has the full field reference. Fields can be added over time, so ignore fields you do not use.

Step 9: Verify the secret

Every request body carries the secret field. Compare it with the key you stored in Step 4 and reject the request with 401 if it does not match. The Code Examples tab shows this check in each language. qlar does not sign requests with a header, so the secret field is the check to rely on.

A few more rules for a robust receiver:

• Answer quickly with a 2xx status. qlar waits up to 10 seconds for each request and does not retry, so do slow work (creating tickets, sending messages) after you respond.
• Process events idempotently, using data.escalationId and eventType, so a duplicate never creates a second ticket.
• Never log the secret value.

Check the result: send a real test event

Run this test flow:

1. In the Preview chat, trigger one escalation, as in Configure Escalation.
2. In the Preview queue, claim it with CLAIM TICKET.
3. Write a resolution note and click COMPLETE.

Your receiver should get escalation.created, escalation.claimed and escalation.completed for the same escalationId, each with the correct secret.

If nothing arrives, check that the webhook is Enabled, that you saved after changing it, that the URL starts with https:// and is reachable from the internet, and, for the live agent, that you published.

Next steps

• Next in the journey: you have finished Stage 2. Start Stage 3 with Search and Read the Web, so your agent can look things up beyond its knowledge.
• Review the whole escalation flow: Hand Off to a Human.
• Receive and Manage Escalations: the supervisor workspace.