---
title: "Receive escalation webhooks"
url: "/help/buuk/guides/receive-escalation-webhooks"
updated: "2026-11-15T11:35:30.335Z"
---
# Receive escalation webhooks

When a reader asks for a person and no live chat is configured, Buuk posts the question to your endpoint. That makes it easy to turn an unanswered question into a Slack message, a Linear issue or a support ticket.

## Set it up

Open Settings → Help widget → Escalation and enter a publicly reachable HTTPS URL. Add a signing secret if you want to verify the sender. The URL must be HTTPS and must not resolve to a private address.

## The request

Buuk sends one JSON object:

```json
{
  "widget": { "key": "wk_...", "workspaceId": "..." },
  "request": { "origin": "https://app.example.com", "userAgent": "..." },
  "context": {
    "pageUrl": "https://app.example.com/settings",
    "articleSlug": "billing",
    "lastSearches": ["invoice vat"],
    "chatSummary": "Reader asked about VAT receipts",
    "question": "Can I get a VAT receipt?",
    "visitor": { "name": "Sam", "email": "sam@example.com" }
  },
  "data": {},
  "createdAt": "2026-11-15T09:12:00.000Z"
}

```

`context` is what the reader was doing: the page, the article they had open, their recent searches and a summary of the conversation. `visitor` only appears after your page called identify.

## Verify the signature

With a secret set, the request carries `x-buuk-signature`: an HMAC-SHA256 of the raw request body, hex encoded. Compute the same digest and compare in constant time:

```js
const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(headers["x-buuk-signature"]));
```

Use the raw body, not a re-serialised object, or the digest won't match.

## Failures

A webhook that doesn't return 2xx is logged, and the reader still sees the confirmation in the widget, so a broken endpoint never blocks a person from asking for help. Watch your endpoint's own error rate rather than the widget's.

Related: Hand off to live chat; Widget settings.