Send Escalation Events to a Webhook
Open in CMSWebhooks 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 section
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 on Send webhook notifications. The hint says: "Get an HTTP POST when an escalation is created, claimed, completed or released." The Webhook URL and Secret key rows appear.
Step 3: Set the webhook URL
Enter your endpoint in Webhook URL. It is required while the webhook is on and must start with https://, as the hint under the field says. If the field is empty or the URL does not start with https://, the field shows Enter a webhook URL. or Start the URL with https://. 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 generated yet. Save to create a key. The key is created when you save.
Step 4: Save, then copy the secret key
- Click Save at the bottom of the Escalation page. A Saved dialog confirms Escalation settings saved.
- The Secret key box now holds the generated key. Click the copy button at its right end (the tooltip says Copy key, then Copied) and store the key in your backend's secret store (for example an environment secret or a vault), not in source control.
The hint explains what the key is for: "Check this key in your webhook handler to confirm a request comes 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
In the API docs row at the bottom of the section, click Show API docs. The documentation opens right below, on the same page, with 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. Pick the language with the tabs in the header of the code block, and use Copy to copy the code.
The button now reads Hide API docs. Click it to collapse the documentation again.

Step 7: Understand the event types
Each request carries one event in eventType:
| Event | When it is sent | Status afterwards |
|---|---|---|
escalation.created | The AI raises a new escalation | Pending |
escalation.updated | The AI escalates a thread that already has an open escalation again | Pending |
escalation.claimed | A supervisor claims the case | InProgress |
escalation.completed | A supervisor completes it | Completed |
escalation.released | An agent Owner or Contributor releases it back to Pending | Pending |
The hint of Send webhook notifications 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
}
}
supervisoris filled in once someone claims the case, andresolutionNoteandcompletedAtwithescalation.completed.urgencyLevelis one oflow,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
2xxstatus. 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.escalationIdandeventType, so a duplicate never creates a second ticket. - Never log the
secretvalue.
Check the result: send a real test event
Run this test flow:
- In the Preview chat, trigger one escalation, as in Configure Escalation.
- In the Preview queue, claim it with CLAIM TICKET.
- 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 Send webhook notifications is on, 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.