Send Escalation Events to Webhook

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

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

Step 1 -- Open Webhook Card in Escalation Settings

In CMS, go to Escalation and scroll to Webhook Notifications.

Validation notes:

• Confirm the Webhook Notifications card is visible in the same Escalation settings page where you manage escalation behavior.
• If the card is missing, verify you are editing the correct agent/environment and that your role has permission to update escalation settings.

Step 2 -- Enable Webhook

Turn the Webhook toggle to Enabled.

When enabled, webhook URL and secret key controls become visible.

Validation notes:

• Immediately after enabling, check that Webhook URL and Secret Key fields appear.
• If they do not appear, refresh once and confirm the toggle still shows Enabled before continuing.

Step 3 -- Set the Webhook URL

Enter your endpoint in Webhook URL.

Requirements:

• URL must be non-empty
• URL must start with https://

Example:

https://your-domain.com/integrations/qlar/escalation

Validation notes:

• Use a production-grade HTTPS endpoint that is reachable from the internet (not localhost).
• Do a quick endpoint check from your backend logs or API gateway to confirm requests to this path are accepted.
• Return a clear non-2xx error for unsupported methods so integration issues are easier to diagnose.

Step 4 -- Copy and Secure the Secret Key

Use the copy button in Secret Key to store the key securely in your backend secret manager.

Do not expose this key in frontend code or public logs.

Validation notes:

• Store the key in a secure secret store (for example, environment secret manager or vault), not in source control.
• Verify your receiver service can read the stored key at runtime.
• Mask the key in logs and dashboards to prevent accidental disclosure.

Step 5 -- Regenerate Key if Needed

If a key is suspected to be leaked, click Regenerate Key and update your webhook receiver immediately.

After regeneration, old signatures should be treated as invalid.

Validation notes:

• Rotate the key in your receiver first (or with zero-downtime secret rollout) to minimize failed deliveries.
• Trigger a test event after rotation and confirm only the new secret validates successfully.
• Any request signed with the old secret should now fail signature verification.

Step 6 -- Save Escalation Settings

Click Save in Escalation page after webhook changes.

No webhook delivery occurs until changes are saved and escalation events happen.

Validation notes:

• Wait for a save success message before leaving the page.
• Reopen Escalation settings and confirm Webhook remains enabled with the expected URL.
• If settings revert, check for validation errors or conflicting edits from another session.

Step 7 -- Understand Escalation Event Types

Webhook notifications are sent for lifecycle events:

Validation notes:

• Make sure your receiver routes logic by eventType and gracefully handles all four events.
• Treat unknown future event values safely (for example, log and skip) instead of failing the entire endpoint.

Step 8 -- Example Payload

Your endpoint should accept JSON payloads similar to this shape:

{
  "eventType": "created",
  "timestamp": "2026-05-19T10:15:00Z",
  "agentId": "agent-123",
  "escalation": {
    "id": "esc-001",
    "threadId": "thread-abc",
    "status": "Pending",
    "urgencyLevel": "high",
    "topic": "refund",
    "area": "payment",
    "reason": "User is angry and demands immediate refund",
    "triggerCondition": "Angry Customer Escalation"
  }
}

Exact payload fields can evolve, so design the receiver to ignore unknown fields safely.

Validation notes:

• Validate required fields for your workflow (for example, eventType, timestamp, and escalation identifiers) and ignore optional extras.
• Keep your parser tolerant to additive schema changes to avoid breaking on new fields.

Step 9 -- Verify Request Signature (Recommended)

Validate incoming requests with HMAC-SHA256 using your webhook secret key.

Recommended verification flow:

1. Read raw request body bytes.
2. Compute HMAC-SHA256 using stored secret.
3. Compare with signature header in constant-time comparison.
4. Reject mismatched signatures with 401 or 403.

Validation notes:

• Always verify against the raw body bytes, not a re-serialized JSON object.
• Reject requests with missing signature headers.
• Log verification failures without logging sensitive request body or secret values.

Step 10 -- Send a Real Test Event

Run this simple test flow:

1. Trigger one angry-user escalation.
2. Claim it from supervisor workspace.
3. Complete it with resolution notes.

You should observe created, claimed, and completed events reaching your webhook receiver.

Validation notes:

• Confirm arrival order and timestamps in your receiver logs.
• Verify each event is processed idempotently so retries do not create duplicate side effects.
• Store request/response traces for a short period to simplify troubleshooting during rollout.

Related Pages

• Automate with Escalation
• Configure Escalation
• Receive and Manage Escalation in Real Time