Developer API, webhooks and customer records
KasaDESK offers three server-to-server integrations, all configured in Admin → Settings → Developer:
- The Public API, a bearer-token REST API your systems call to read conversations, messages and customers, and to send replies.
- Webhooks, signed HTTPS callbacks that KasaDESK sends to your server when public conversation events happen.
- Customer records, a read-only endpoint on your system that KasaDESK calls to show a verified customer’s account status and recent orders to agents.
For the website embed, WordPress plugin, signed customer identity, Help Center WebViews and the React Native customer SDK, see Customer integrations.
Examples use https://support.example.com for your KasaDESK installation and synthetic data only. Every credential shown is a placeholder.
The Developer screenLink to this section
Open Admin → Settings → Developer. Only owners and admins can open it. Supervisors and agents who open the page are sent to the inbox, and the server refuses their requests to the developer settings.
The page has two tabs:
| Tab | Contents |
|---|---|
| API & integrations | The settings: Public API (this installation’s base URL and OpenAPI link), API keys, Webhooks and Customer records. |
| Developer docs | In-product documentation with one section per setting: 1. Public API, 2. API keys, 3. Webhooks and 4. Customer records. A contents box stays in view while you scroll. Addresses in its examples are built from the installation you are signed in to. |
The Developer docs tab has its own address, /admin/settings/developer?tab=docs, so you can bookmark it or share it with another admin.
Credentials and what each one is forLink to this section
KasaDESK uses several credentials. They are not interchangeable, and each one only works in its own place.
| Credential | Format | Who creates it | Direction | Where it belongs | Shown again? |
|---|---|---|---|---|---|
| Site key | pk_… |
KasaDESK, per Web Chat channel | Browser or app → KasaDESK | Page HTML, app bundle, WordPress settings. It is publishable and is not a secret. | Yes, on the channel |
| Identity secret | Random value | KasaDESK, per Web Chat channel | Your backend signs customer identity tokens | Your backend or wp-config.php only |
No. Shown once, on creation or rotation |
| API key | kd_live_… |
An admin, in API keys | Your server → KasaDESK Public API | Your server’s secret store | No. Shown once; only a hash is stored |
| Webhook signing secret | whsec_… |
KasaDESK, per webhook endpoint | KasaDESK signs → your receiver verifies | Your webhook receiver’s secret store | No. Shown once, on creation and on each rotation |
| Customer records API key | 16–500 printable characters, no spaces | You (or the WordPress plugin’s Generate API key) | KasaDESK → your records endpoint | Your records service, and entered once in KasaDESK | No. Stored encrypted and write-only |
| Provider credentials | Bot tokens, app secrets, API keys, mailbox passwords | Your provider accounts | KasaDESK → Telegram, Meta, Twilio, TikTok, email and other providers | Entered in Channels & Integrations | No. Encrypted and write-only |
Keep these rules in mind:
- An API key cannot sign identity tokens, and an identity secret cannot call the Public API.
- The Public API never accepts a staff sign-in. A browser session cookie, or a staff phone app session, gets
401. - Provider credentials are never used with the Public API. See Channels and provider setup.
- Customer records require the identity secret to be in use, because records are shown only for customers your site has verified. See Verified identity and ticket continuity.
API keysLink to this section
Create a key with least privilegeLink to this section
- Open API & integrations → API keys.
- Enter a Key name (up to 120 characters) that says where it is used, for example CRM sync. The name also appears as the author of replies sent with the key.
- Optionally set Expires (optional). It is entered in your browser’s local time and must be in the future. After it passes, the key stops working.
- Under Workspaces, tick only the workspaces (brands) the integration needs. A key can cover one or more workspaces.
- Under Access, choose the scopes:
- Read conversations, messages and customers (
read) is ticked by default. - Send replies (
write) lets the key post replies. Give it only to integrations that send messages.
- Read conversations, messages and customers (
- Choose Create API key. Copy the key from the box New API key: copy it now. It will not be shown again., store it in your secret manager, then choose I have stored it.
- Check the key with
GET /me(see Check a key).
Choosing scopes:
| Integration | Scopes |
|---|---|
| Reporting, CRM sync, data export | read only |
| Bot or order system that replies and also reads history | read and write |
| System that only posts replies to conversation IDs it receives from webhooks | write only. It can call /me and post replies, but gets 403 on every read. |
Use one key per integration, so you can revoke one without breaking the others. Keep keys on servers. Never put a key in a website, a mobile app, a browser extension or a source repository.
What the key list showsLink to this section
Each key shows its name, its first characters (for example kd_live_AbCdEf…), its scopes, its workspaces, when and by whom it was created, when it was last used, its expiry and a status of active, expired or revoked. Last used is updated at most every 30 seconds. The server also records the IP address of the last use.
Revoke, expire and replaceLink to this section
- Revoke asks for confirmation (Integrations using it stop working immediately) and takes effect on the next request. Revoked keys stay in the list with the status revoked. A revoked key cannot be restored.
- An expired key stops working at its expiry time and shows expired.
- Keys cannot be edited. To change a key’s name, workspaces, scopes or expiry, or to rotate it, create a replacement.
To replace a key without downtime:
- Create a new key with the scopes and workspaces you want.
- Deploy it to your integration.
- Confirm it with
GET /me, and check that the new key’s last used time updates. - Revoke the old key.
Revoked, expired and unknown keys all receive the same 401 invalid_api_key, so the response does not reveal which one it was.
Workspaces and isolationLink to this section
- A key sees only the workspaces it was given. Archiving a workspace removes it from every key automatically.
- A direct conversation lookup returns
404when the conversation falls outside the key’s workspaces. Customer lookup is list-only and never returns records outside the key’s workspace scope. - The
workspaceIdfilter can only narrow results to one of the key’s workspaces. Any other value returns an empty list.
Each key creation and revocation is recorded in the Audit log as api_key.created and api_key.revoked.
Public APILink to this section
Base URL and specificationLink to this section
| Item | Value |
|---|---|
| Base URL | https://support.example.com/api/v1/public-api |
| OpenAPI 3.1 document | https://support.example.com/api/v1/public-api/openapi.json |
| Authentication | Authorization: Bearer kd_live_… |
| Request bodies | JSON, with Content-Type: application/json |
Download the bundled OpenAPI 3.1 reference for the reviewed routes and schemas. It uses an example origin. The deployed OpenAPI document needs no authentication. It is served by your installation, with its servers URL taken from your PUBLIC_API_ORIGIN, and is cached for up to five minutes. It also describes every webhook payload. Use the document from your own installation as the definitive field list for the version you run, and import it into Postman, Insomnia or a code generator.
curl -fsS https://support.example.com/api/v1/public-api/openapi.json -o kasadesk-openapi.jsonEndpointsLink to this section
All paths are relative to the base URL.
| Request | Scope | Inputs | Success output |
|---|---|---|---|
GET /openapi.json |
None (anonymous) | None | 200 OpenAPI 3.1 document |
GET /me |
Any valid key | None | 200 { id, name, scopes, workspaceIds } |
GET /conversations |
read |
Query: workspaceId (UUID), lifecycle (open, pending or resolved), reference (for example T-0000C, case-insensitive, optional #, up to 8 characters), limit (1–100, default 25), cursor |
200 { data: Conversation[], nextCursor }, newest activity first |
GET /conversations/{id} |
read |
Path: conversation UUID | 200 { data: Conversation } |
GET /conversations/{id}/messages |
read |
Path: conversation UUID. Query: limit (1–500, default 200) |
200 { data: Message[] }, oldest first |
POST /conversations/{id}/replies |
write |
Path: conversation UUID. Body: body (1–20,000 characters after trimming). Idempotency key (8–100 characters) in the body as idempotencyKey or in the Idempotency-Key header. Required. |
201 { data: { messageId, duplicate: false } }, or 200 { data: { messageId, duplicate: true } } for a repeated key |
GET /customers |
read |
Query: workspaceId (UUID), email (exact, case-insensitive), limit (1–100, default 25), cursor |
200 { data: Customer[], nextCursor }, newest first |
IDs and referencesLink to this section
- Path parameters take the record’s UUID, the
idfield. A reference such asT-0000Cin the path returns404. - To find a conversation by its reference, list with
?reference=T-0000C, then use the returnedid. - References are short, stable labels shown to staff and customers. They do not grant access.
PaginationLink to this section
List responses contain nextCursor. Pass it unchanged as cursor to get the next page. It is null on the last page.
- Treat the cursor as opaque. Do not build or edit one. A malformed cursor returns
400 bad_cursor. - Repeat the same filters with every page. The cursor marks a position, not a query.
GET /conversationssorts by the latest message time (or the creation time when there is none), newest first.GET /customerssorts by creation time, newest first.GET /conversations/{id}/messageshas no cursor. It returns up tolimitmessages, oldest first.
What the API exposesLink to this section
| Resource | Fields |
|---|---|
| Conversation | id, reference, subject, lifecycle (open, pending, resolved), handler (ai, human, queued), priority (low, normal, high, urgent), workspace, workgroup, channel (with type and label), customer (with name, email and verification: guest, unverified or verified), assignee or null, lastMessagePreview, lastMessageAt, createdAt, slaDueAt |
| Message | id, reference, conversationId, conversationReference, authorType (customer, agent, ai, system), authorName, body, deliveryStatus (none, queued, sending, accepted, delivered, read, failed), createdAt, attachments |
| Customer | id, reference, workspaceId, workspaceReference, name, email, phone, verification, createdAt |
- Internal notes are never returned, in lists, previews or message history.
- Messages do not include staff account IDs or a visibility flag.
authorNameis the staff member’s name for agent replies, the key’s name for replies sent with an API key, and the customer’s name for customer messages. - Attachments are listed as metadata only:
id,filename,contentTypeandsize. The Public API does not download attachment files. - Spam conversations, and conversations in archived workspaces, are not listed.
- Customer records include
phone. Givereadonly to systems that may hold customer contact data.
Send a replyLink to this section
POST /conversations/{id}/replies sends a public reply through the conversation’s own channel: the web chat, the mailbox, the Telegram bot or whichever channel the customer used. You cannot choose another channel or sending account.
- Email replies go through the outbox, which retries delivery.
- A channel that cannot send replies returns
409 channel_outbound_unavailable. - Rules that apply to agent replies, such as a provider’s messaging window, also apply to API replies.
- The reply is stored with
authorType: "agent"and the key’s name asauthorName. Like an agent reply, it hands the conversation to staff and pauses automatic AI replies for it. - Each new reply is recorded in the Audit log as
public_api.reply, with the key’s ID.
Idempotency. Every reply needs an idempotency key, so a retry never sends twice. Repeating a key returns 200 with duplicate: true and the original messageId, whatever body you send. Duplicate detection is scoped to the API key and conversation. A retry using a replacement API key is a new attempt for deduplication purposes. Use a value tied to the business event, for example order-1042-shipped, and never reuse one for a different message.
Errors and status codesLink to this section
Errors use one JSON shape:
{ "error": { "code": "insufficient_scope", "message": "This API key does not have the write scope" } }| Status | error.code |
When |
|---|---|---|
400 |
bad_cursor |
The cursor is not one KasaDESK issued. |
400 |
bad_json |
The request body is not valid JSON. |
401 |
invalid_api_key |
The key is missing, malformed, unknown, expired or revoked, or a staff session was sent instead. The response includes a WWW-Authenticate: Bearer realm="kasadesk" header. |
403 |
insufficient_scope |
The key lacks read or write for this request. |
404 |
not_found |
The conversation does not exist, is outside the key’s workspaces, or the path is not a UUID. Unknown API paths also return 404. |
409 |
channel_outbound_unavailable or channel_disabled |
The origin channel cannot send replies, or the outbound provider channel is disabled. Check the channel before retrying. |
422 |
validation_failed |
A field is invalid, or the idempotency key is missing. Field errors may include details. |
429 |
rate_limited |
The key exceeded its rate limit. |
500 |
internal |
Unexpected server error. Retry later with the same idempotency key. |
Rate limitsLink to this section
- Each API key may make 300 requests in any 60-second window by default. The operator changes this with the server setting
PUBLIC_API_RATE_PER_MINUTE. - The limit is per key. One busy key does not slow down another.
- Over the limit, the API returns
429 rate_limited. NoRetry-Afterheader is sent. Back off with increasing delays, for example 5, 10, then 30 seconds, and retry. GET /openapi.jsonis not counted against any key.
Copy-ready requestsLink to this section
Set these once in your shell. The values are placeholders.
export KASADESK_URL="https://support.example.com"
export KASADESK_API_KEY="kd_live_EXAMPLE_ONLY_REPLACE_WITH_YOUR_KEY"
export KASADESK_API="$KASADESK_URL/api/v1/public-api"Check a keyLink to this section
curl -fsS "$KASADESK_API/me" -H "Authorization: Bearer $KASADESK_API_KEY"{
"id": "0b6f3c1e-8a52-4d0e-9c41-3f2a7d5e9b10",
"name": "CRM sync",
"scopes": ["read"],
"workspaceIds": ["5d1e2f3a-4b5c-4d6e-8f70-1a2b3c4d5e6f"]
}List open conversations in one workspaceLink to this section
curl -fsS -G "$KASADESK_API/conversations" \
-H "Authorization: Bearer $KASADESK_API_KEY" \
--data-urlencode "workspaceId=5d1e2f3a-4b5c-4d6e-8f70-1a2b3c4d5e6f" \
--data-urlencode "lifecycle=open" \
--data-urlencode "limit=10"An abridged response. The OpenAPI document lists every field.
{
"data": [
{
"id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"reference": "T-0000C",
"subject": null,
"lifecycle": "open",
"handler": "human",
"priority": "normal",
"workspace": { "id": "5d1e2f3a-4b5c-4d6e-8f70-1a2b3c4d5e6f", "reference": "W-0000A", "name": "Harbor Studio" },
"channel": { "id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f", "type": "web_widget", "label": "Harbor website chat" },
"customer": { "id": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b", "name": "Ama Mensah", "email": "[email protected]", "verification": "verified" },
"assignee": null,
"lastMessagePreview": "Where is my order?",
"lastMessageAt": "2026-11-21T10:15:00.000Z",
"createdAt": "2026-11-21T10:14:12.000Z",
"slaDueAt": "2026-11-21T11:14:12.000Z"
}
],
"nextCursor": "MjAyNi0xMS0yMVQxMDoxNTowMC4wMDBafDlhOGI3YzZkLTVlNGYtNGEzYi04YzJkLTFlMGY5YThiN2M2ZA"
}Find a conversation by its referenceLink to this section
curl -fsS -G "$KASADESK_API/conversations" \
-H "Authorization: Bearer $KASADESK_API_KEY" \
--data-urlencode "reference=T-0000C"Page through every open conversationLink to this section
This loop requires jq.
cursor=""
while :; do
page=$(curl -fsS -G "$KASADESK_API/conversations" \
-H "Authorization: Bearer $KASADESK_API_KEY" \
--data-urlencode "lifecycle=open" \
--data-urlencode "limit=100" \
${cursor:+--data-urlencode "cursor=$cursor"}) || exit 1
printf '%s\n' "$page" | jq -r '.data[] | [.reference, .id, .customer.name] | @tsv'
cursor=$(printf '%s\n' "$page" | jq -r '.nextCursor // empty')
[ -z "$cursor" ] && break
doneRead one conversation and its messagesLink to this section
export CONVERSATION_ID="9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"
curl -fsS "$KASADESK_API/conversations/$CONVERSATION_ID" \
-H "Authorization: Bearer $KASADESK_API_KEY"
curl -fsS "$KASADESK_API/conversations/$CONVERSATION_ID/messages?limit=500" \
-H "Authorization: Bearer $KASADESK_API_KEY"{
"data": [
{
"id": "1f2e3d4c-5b6a-4978-8a6b-5c4d3e2f1a0b",
"reference": "M-0000F",
"conversationId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"conversationReference": "T-0000C",
"authorType": "customer",
"authorName": "Ama Mensah",
"body": "Where is my order?",
"deliveryStatus": "none",
"createdAt": "2026-11-21T10:14:12.000Z",
"attachments": []
}
]
}Send a replyLink to this section
Use a test conversation UUID and a key with write. This sends a customer-visible reply. In the isolated test, the first command returns 201 and its identical retry returns 200 with "duplicate": true.
curl -sS -X POST "$KASADESK_API/conversations/$CONVERSATION_ID/replies" \
-H "Authorization: Bearer $KASADESK_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042-shipped" \
-d '{"body":"Good news: order 1042 has shipped and should arrive on 22 November."}' \
-w '\nHTTP %{http_code}\n'{ "data": { "messageId": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d", "duplicate": false } }Find a customer by emailLink to this section
curl -fsS -G "$KASADESK_API/customers" \
-H "Authorization: Bearer $KASADESK_API_KEY" \
--data-urlencode "[email protected]"WebhooksLink to this section
A webhook endpoint is a URL on your server that KasaDESK calls with a signed JSON POST when a public event happens in one workspace. Use webhooks instead of polling the Public API.
Add an endpointLink to this section
- Open API & integrations → Webhooks.
- Choose the Workspace. An endpoint belongs to exactly one workspace and receives events only from it. Add one endpoint per workspace if you need several brands.
- Optionally enter a Description (optional), up to 300 characters.
- Enter the Endpoint URL, for example
https://hooks.example.com/kasadesk. - Under Events, tick the event types, or use Select all.
- Choose Add endpoint. Copy the Signing secret (
whsec_…) from the box that appears, store it with your receiver’s secrets, and choose I have stored it. It is not shown again. - Choose Send test and check that your receiver verified it.
The console has no form to change an endpoint’s URL or events after it is created. Add a new endpoint with the new settings, check it with Send test, then Delete the old one. Deleting an endpoint also deletes its delivery log.
Endpoint URL restrictionsLink to this section
| Rule | Production | Non-production |
|---|---|---|
| Scheme | https only |
https or http |
Credentials in the URL (user:password@) |
Refused | Refused |
| Private, loopback, link-local, CGNAT, documentation, multicast and reserved addresses, IPv4 and IPv6 | Refused | Refused, unless the operator sets WEBHOOK_ALLOW_PRIVATE_TARGETS=true. The panel then says Private network destinations are allowed in this non-production environment. |
| Host names | Must resolve. Every resolved address is checked again when KasaDESK connects, so a DNS answer that changes later cannot reach a private address. | Same, unless private targets are allowed |
| Redirects | Not followed. A 3xx counts as a failure. |
Same |
WEBHOOK_ALLOW_PRIVATE_TARGETS is always ignored in production.
EventsLink to this section
Tick only the events your integration uses. Events are sent only when KasaDESK records a public conversation event. Internal notes, AI internals and read receipts are never offered and never sent.
| Event | Sent when |
|---|---|
conversation.created |
A new conversation starts. |
conversation.reopened |
A resolved conversation is opened again. |
conversation.status |
The status changes between open, pending and resolved. |
conversation.priority |
The priority changes. |
conversation.assigned |
The conversation is assigned to a staff member. |
conversation.unassigned |
The assignee is removed. |
conversation.moved |
The conversation moves to another workgroup. |
conversation.escalated |
The conversation is escalated. |
conversation.human_takeover |
Staff take over from the AI. |
conversation.ai_resumed |
Automatic AI replies are switched back on. |
message.created |
A public message is added by the customer, staff, the AI or the API. |
message.delivery |
A sent message’s delivery status changes. |
webhook.test |
You choose Send test. Always sent on request; not selectable. |
The release’s automated tests deliver webhook.test and message.created end to end to a local receiver. When you subscribe to other events, confirm each one on a test installation with the actions your integration depends on.
Request headersLink to this section
| Header | Value |
|---|---|
Content-Type |
application/json |
User-Agent |
KasaDesk-Webhooks/1 |
X-KasaDesk-Event-Id |
The event ID, for example evt_1042. Identical on every retry and redelivery. Test events use evt_test_…. |
X-KasaDesk-Event-Type |
The event type, for example message.created. |
X-KasaDesk-Delivery-Id |
This delivery’s UUID, as shown in the delivery log. |
X-KasaDesk-Timestamp |
When this attempt was signed, in Unix seconds. |
X-KasaDesk-Signature |
v1=<hex HMAC-SHA256>. During a secret rotation, two values separated by a comma. |
PayloadLink to this section
{
"id": "evt_1042",
"type": "message.created",
"createdAt": "2026-11-21T10:14:12.000Z",
"workspaceId": "5d1e2f3a-4b5c-4d6e-8f70-1a2b3c4d5e6f",
"workspaceReference": "W-0000A",
"data": {
"conversation": { "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "reference": "T-0000C", "lifecycle": "open" },
"actorType": "customer",
"changes": { "messageId": "1f2e3d4c-5b6a-4978-8a6b-5c4d3e2f1a0b" },
"message": {
"id": "1f2e3d4c-5b6a-4978-8a6b-5c4d3e2f1a0b",
"reference": "M-0000F",
"conversationId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"conversationReference": "T-0000C",
"authorType": "customer",
"authorName": "Ama Mensah",
"body": "Where is my order?",
"deliveryStatus": "none",
"createdAt": "2026-11-21T10:14:12.000Z",
"attachments": []
}
}
}The conversation object above is abridged. It has the same fields as the Public API’s Conversation.
data.conversationis the conversation as it stood when KasaDESK first tried to deliver the event. Retries resend that same body.data.actorTypeiscustomer,agent,ai,apiorsystem.data.changesholds only allow-listed fields:from,to,fromName,toName,assigneeId,assigneeName,previousAssigneeId,auto,status,attempt,reason,nextStaffedAtandmessageId. Which ones appear depends on the event.data.messageis present formessage.created(the full public message) andmessage.delivery(id,referenceanddeliveryStatusonly).- An event whose message is internal or no longer exists is not sent. Its delivery is marked skipped.
A test event has no conversation data:
{
"id": "evt_test_2f0c6a8e-1b4d-4c7a-9e3f-5d6b7a8c9d0e",
"type": "webhook.test",
"createdAt": "2026-11-21T10:20:00.000Z",
"workspaceId": "5d1e2f3a-4b5c-4d6e-8f70-1a2b3c4d5e6f",
"data": { "message": "This is a test delivery from KasaDESK. No conversation data is included." }
}Verify the signature in Node.jsLink to this section
The signature is HMAC-SHA256, in lowercase hex, over the bytes <X-KasaDesk-Timestamp>.<raw request body>, keyed with the endpoint’s signing secret. To verify it:
- Read the raw body bytes before any JSON parsing. Re-serialized JSON will not match.
- Reject timestamps more than 5 minutes from your clock, to limit replays.
- Compare in constant time against each
v1=value in the header. Accept the request if any one matches.
Save this as verify-kasadesk-webhook.mjs:
import crypto from 'node:crypto';
const TOLERANCE_SECONDS = 300;
/**
* @param {string} secret the endpoint's whsec_… signing secret
* @param {Buffer} rawBody the request body exactly as received
* @param {string} timestampHeader X-KasaDesk-Timestamp
* @param {string} signatureHeader X-KasaDesk-Signature
*/
export function verifyKasaDeskSignature(secret, rawBody, timestampHeader, signatureHeader, nowMs = Date.now()) {
const timestamp = String(timestampHeader ?? '');
if (!/^\d{9,12}$/.test(timestamp)) return false;
if (Math.abs(Math.floor(nowMs / 1000) - Number(timestamp)) > TOLERANCE_SECONDS) return false;
const expected = Buffer.from(
'v1=' + crypto.createHmac('sha256', secret).update(`${timestamp}.`).update(rawBody).digest('hex'),
);
return String(signatureHeader ?? '')
.split(',')
.map((value) => Buffer.from(value.trim()))
.some((candidate) => candidate.length === expected.length && crypto.timingSafeEqual(candidate, expected));
}Check it locally with a synthetic secret and body, without KasaDESK. Save as self-test.mjs next to it and run node self-test.mjs:
import crypto from 'node:crypto';
import { verifyKasaDeskSignature } from './verify-kasadesk-webhook.mjs';
const secret = 'whsec_EXAMPLE_ONLY_NOT_A_REAL_SECRET';
const body = Buffer.from(JSON.stringify({ id: 'evt_test_example', type: 'webhook.test', data: {} }));
const timestamp = String(Math.floor(Date.now() / 1000));
const signature = 'v1=' + crypto.createHmac('sha256', secret).update(`${timestamp}.`).update(body).digest('hex');
console.log(verifyKasaDeskSignature(secret, body, timestamp, signature)); // true
console.log(verifyKasaDeskSignature(secret, Buffer.concat([body, Buffer.from(' ')]), timestamp, signature)); // false: body changed
console.log(verifyKasaDeskSignature('whsec_OTHER_EXAMPLE', body, timestamp, signature)); // false: wrong secret
console.log(verifyKasaDeskSignature(secret, body, String(Number(timestamp) - 3600), signature)); // false: staleThis runnable Express receiver demonstrates verification and deduplication for a local test. Install Express with npm install express and save it as receiver.mjs. Place the raw-body route before any JSON middleware. In production, durably enqueue the verified event using its ID as a unique key before acknowledging delivery.
import express from 'express';
import { verifyKasaDeskSignature } from './verify-kasadesk-webhook.mjs';
const app = express();
const signingSecret = process.env.KASADESK_WEBHOOK_SECRET;
if (!signingSecret) throw new Error('Set KASADESK_WEBHOOK_SECRET before starting the receiver.');
const handled = new Set(); // local demonstration only
app.post('/kasadesk', express.raw({ type: 'application/json', limit: '1mb' }), (req, res) => {
const rawBody = Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0);
const valid = verifyKasaDeskSignature(
signingSecret,
rawBody,
req.get('x-kasadesk-timestamp'),
req.get('x-kasadesk-signature'),
);
if (!valid) return res.sendStatus(401);
let event;
try {
event = JSON.parse(rawBody.toString('utf8'));
} catch {
return res.sendStatus(400);
}
const eventId = req.get('x-kasadesk-event-id');
if (!eventId || event?.id !== eventId || event?.type !== req.get('x-kasadesk-event-type')) {
return res.sendStatus(400);
}
if (handled.has(eventId)) return res.sendStatus(204);
handled.add(eventId);
console.log('received', event.type, eventId);
return res.sendStatus(204);
});
app.listen(3000);Run it with KASADESK_WEBHOOK_SECRET=whsec_EXAMPLE_ONLY_NOT_A_REAL_SECRET node receiver.mjs, behind HTTPS.
Delivery, retries and deduplicationLink to this section
- Success is any
2xxanswer within 10 seconds. The response body is ignored. Durably record the event ID and queue the work before acknowledging. Process the queued work separately. - Failures are any other status, a timeout, a connection error, a blocked address or a redirect.
- Retry schedule. After a failed attempt KasaDESK tries again after 30 seconds, 2 minutes, 10 minutes, 30 minutes, 2 hours and 6 hours. After the seventh failed attempt the delivery is marked dead.
- Auto-disable. After 15 consecutive failed attempts across the endpoint’s deliveries, the endpoint is disabled and shows Disabled after repeated failures. The event is recorded in the Audit log as
webhook.auto_disabled. Pending deliveries wait. Fix your receiver, then choose Enable: the failure count resets and waiting deliveries resume with the same event IDs. A successful delivery also resets the count. - Deduplicate on
X-KasaDesk-Event-Id. Deliveries are at least once. The same event can arrive more than once through a retry, a Redeliver, or a slow answer that KasaDESK timed out on. - Ordering is not guaranteed. Use
createdAtand the current state from the Public API when order matters. - Deliveries are sent by the background workers. They are not sent while workers are stopped. See Scale and run workers. Operators can watch
kasadesk_webhook_queue_depth. See Monitor the installation.
| Delivery status | Meaning |
|---|---|
| pending | Waiting for its next attempt, shown with its next time. Also used while the endpoint is disabled. |
| sending | An attempt is in progress. |
| succeeded | Your receiver answered 2xx. |
| dead | All seven attempts failed. |
| skipped | The event was not deliverable, for example because its message is internal or was removed. |
Test, history and redeliveryLink to this section
- Send test sends a signed
webhook.testimmediately, using the same headers and signing as real events, and opens the delivery log. The notice reads Test delivery succeeded, or Test delivery failed: with the error or HTTP status. Test deliveries are tried once, are never retried, never count towards auto-disable and cannot be redelivered. - Delivery log shows the 50 most recent deliveries with Time, Event (with the event ID and (test) for tests), Status, Attempts (HTTP code), for example
#1: 204 · 38 ms, and Actions. Refresh reloads it. - Redeliver is offered on finished, non-test deliveries (succeeded, dead or skipped). It queues the same delivery again with the same event ID and a fresh attempt count. A redelivered skipped event is skipped again if it is still not deliverable.
- Disable and Enable pause and resume an endpoint. Delete removes it and its log after confirmation.
The operational clean-up in Retention removes finished deliveries after a fixed age, except for workspaces on legal hold. See Data retention.
Rotate the signing secretLink to this section
- Choose Rotate secret on the endpoint.
- Copy the new Signing secret from the box that appears.
- For the next 24 hours, KasaDESK signs every delivery with both the new and the previous secret. The header carries two
v1=values, and the endpoint shows previous secret valid until …. - Deploy the new secret to your receiver within that window. A receiver that accepts any matching
v1=value keeps working throughout. - After 24 hours only the new secret is used.
If a secret may have leaked, rotate it at once and deploy the new one quickly. Rotations are recorded in the Audit log as webhook.secret_rotated.
Customer recordsLink to this section
Customer records connect one Web Chat channel (shown in the console as a chat site) to a read-only endpoint on your own system. When a verified customer chats on that channel, agents can open Customer records in the inbox’s Customer details panel and see the customer’s account status and up to five recent orders. Optionally, the AI can use the same records.
The WordPress plugin provides this endpoint for WooCommerce stores. See Customer records for verified customers.
Who sees whatLink to this section
| Person | Access |
|---|---|
| Owners and admins | Configure the connection under Developer → API & integrations → Customer records. |
| Staff with access to the conversation | Open Customer records in the conversation’s Customer details panel. Opening it starts a live lookup. |
| AI | Only when Allow AI to use these records is ticked for that chat site. Off by default. |
| Customers | Nothing. Records are shown to staff only. |
Records are looked up only for a conversation whose customer was verified by a signed identity token from your site or app, using the sub from that token. A typed email address or order number never unlocks records. Every lookup is written to the Audit log as customer_context.lookup with the outcome only, never the records.
Build the endpointLink to this section
Your endpoint is one HTTPS URL that receives two kinds of POST from KasaDESK:
POST /kasadesk/customer-records HTTP/1.1
Host: records.example.com
Authorization: Bearer <customer records API key>
Accept: application/json
Content-Type: application/json
{"mode":"test"}Answer 200 with Content-Type: application/json and exactly {"ok":true}.
POST /kasadesk/customer-records HTTP/1.1
Host: records.example.com
Authorization: Bearer <customer records API key>
Accept: application/json
Content-Type: application/json
{"mode":"lookup","subject":"customer-42"}Answer 200 with Content-Type: application/json:
{
"subject": "customer-42",
"accountStatus": "active",
"orders": [
{ "reference": "1042", "status": "shipped", "placedOn": "2026-11-18", "estimatedDeliveryOn": "2026-11-22" },
{ "reference": "1017", "status": "delivered", "placedOn": "2026-10-30", "estimatedDeliveryOn": null }
]
}| Field | Rule |
|---|---|
subject |
Required. Must equal the subject KasaDESK sent, 1–200 characters. A different value makes the lookup unavailable. |
accountStatus |
Optional. active, pending, suspended, closed or null. |
orders |
Required, at most 5, newest first. Return [] for an unknown customer. More than five makes the whole answer invalid. |
orders[].reference |
Up to 64 characters. Starts with a letter, digit or #, then letters, digits and . _ / # -. |
orders[].status |
pending, processing, on_hold, shipped, delivered, completed, cancelled, refunded or failed. |
orders[].placedOn, orders[].estimatedDeliveryOn |
Optional. YYYY-MM-DD or null. |
Response limits:
- Answer within 4 seconds, in at most 32 KiB, with status
200and anapplication/jsoncontent type. Anything else, including a redirect, counts as unavailable. - Fields other than those above are dropped and never shown. Still, send only what an agent may see. Never include payment details, passwords or full addresses.
A minimal Node.js endpoint with synthetic data. Install Express with npm install express:
import crypto from 'node:crypto';
import express from 'express';
const recordsKey = process.env.KASADESK_RECORDS_KEY;
if (!recordsKey) throw new Error('Set KASADESK_RECORDS_KEY before starting the endpoint.');
const RECORDS = { // synthetic example data; read from your own system instead
'customer-42': {
accountStatus: 'active',
orders: [{ reference: '1042', status: 'shipped', placedOn: '2026-11-18', estimatedDeliveryOn: '2026-11-22' }],
},
};
const sameSecret = (given, expected) => {
const a = crypto.createHash('sha256').update(given).digest();
const b = crypto.createHash('sha256').update(expected).digest();
return crypto.timingSafeEqual(a, b);
};
const app = express();
app.post('/kasadesk/customer-records', express.json({ limit: '4kb' }), (req, res) => {
const auth = req.get('authorization') ?? '';
if (!sameSecret(auth, `Bearer ${recordsKey}`)) return res.sendStatus(401);
if (req.body?.mode === 'test') return res.json({ ok: true });
if (req.body?.mode !== 'lookup' || typeof req.body.subject !== 'string' ||
req.body.subject.length === 0 || req.body.subject.length > 200) return res.sendStatus(400);
const record = Object.hasOwn(RECORDS, req.body.subject) ? RECORDS[req.body.subject] : null;
res.json({
subject: req.body.subject,
accountStatus: record?.accountStatus ?? null,
orders: (record?.orders ?? []).slice(0, 5),
});
});
app.listen(3001);Start the example with your test value in KASADESK_RECORDS_KEY. Serve it behind HTTPS. From a machine that can reach the endpoint, exercise the two request modes with the same test key:
export RECORDS_KEY="EXAMPLE_ONLY_records_key_0123456789"
curl -sS -X POST https://records.example.com/kasadesk/customer-records \
-H "Authorization: Bearer $RECORDS_KEY" -H "Content-Type: application/json" \
-d '{"mode":"test"}' -w '\nHTTP %{http_code} %{content_type}\n'
curl -sS -X POST https://records.example.com/kasadesk/customer-records \
-H "Authorization: Bearer $RECORDS_KEY" -H "Content-Type: application/json" \
-d '{"mode":"lookup","subject":"customer-42"}' -w '\nHTTP %{http_code} %{content_type}\n'Connect it in KasaDESKLink to this section
Server encryption must be configured to store the key. Without it the panel says Configure server encryption to store a customer records API key.
- Open Developer → API & integrations → Customer records. If the panel asks you to add a chat site first, create a Web Chat channel. See Web Chat.
- Choose the Chat site, listed as workspace · channel label.
- Enter the Customer records endpoint and the Customer records API key, then choose Save connection. The key is stored encrypted and is never shown again. To change it later, enter a value in Replace customer records API key (optional).
- Choose Test endpoint. KasaDESK sends
{"mode":"test"}. The notice reads Endpoint test passed. Enable customer records and save to start lookups. - Tick Enable customer records and choose Save connection. Tick Allow AI to use these records only if the AI may mention order status in its answers.
Endpoint rules:
httpsonly, without credentials, a query string or a fragment.- Private and loopback addresses are refused, both as typed and when the host name resolves. Only a non-production installation with
WEBHOOK_ALLOW_PRIVATE_TARGETS=truemay usehttponlocalhost,127.0.0.1or::1for local testing.
Changing the endpoint or the key resets the test status to Endpoint test required and switches lookups off until a new test passes. A failed test also switches lookups off.
LimitsLink to this section
| Limit | Value |
|---|---|
| Lookups per chat site | 120 per minute. Beyond that, lookups show as unavailable. |
| Test endpoint | 10 per minute per admin |
| Timeout | 4 seconds |
| Response size | 32 KiB |
| Orders shown | 5 |
What agents seeLink to this section
| Agents see | Meaning |
|---|---|
| The account status and orders | Your endpoint answered with records. |
| No account or order records were returned for this customer. | Your endpoint answered with no account status and no orders. |
| The customer must sign in through the connected site or app before records can be shown. | The customer is a guest or unverified. |
| Customer records are temporarily unavailable. with Retry | The endpoint did not answer correctly in time, the subject did not match, or the rate limit was reached. Check it with Test endpoint. |
| Customer records are no longer connected for this site. | Customer records are switched off for this chat site. |
If the connection’s settings change while a lookup is in flight, KasaDESK discards that answer and shows the records as unavailable.
Smoke checksLink to this section
Run these on a test installation with synthetic data and test accounts. Each expected result comes from the release’s own behaviour.
API keys and Public API
-
curl -fsS https://support.example.com/api/v1/public-api/openapi.jsonreturns the document without a key. -
GET /mewith a new key returns its name, scopes and workspace IDs. - A request without a key, with a revoked key, or with only a signed-in browser session returns
401 invalid_api_key. - A read-only key gets
403 insufficient_scopeonPOST /conversations/{id}/replies. - A key for workspace A gets
404for a conversation in workspace B, and?workspaceId=<workspace B>returns an empty list. - After a staff member adds an internal note, neither the list preview nor the messages contain the note’s text.
- Two replies with the same
Idempotency-Keyreturn201, then200with"duplicate": true, and the customer receives one message. - Signed in as an agent, opening
/admin/settings/developerlands on the inbox.
Webhooks
- Send test to your receiver shows Test delivery succeeded, and the delivery log shows
webhook.test (test)with#1:and your receiver’s status code. - Your receiver verifies the signature with the revealed secret, and rejects the same body with one byte changed.
- A test customer message produces a signed
message.createdwhosedata.conversation.idmatches the conversation. An internal note produces nothing. - With your receiver answering
500, the delivery log shows failed attempts and a next retry time. After you fix it, the same event ID arrives and the delivery shows succeeded. - After Rotate secret, the next test delivery carries two
v1=values, and both secrets verify.
Customer records
- Test endpoint passes, and Enable customer records becomes available.
- A verified test customer’s conversation shows the synthetic orders after Customer records is opened. A guest conversation shows the sign-in message.
- The Audit log shows
customer_context.lookupfor each lookup.
Related chaptersLink to this section
- Customer integrations: website embed, WordPress, verified identity, Help Center WebViews and the React Native SDK.
- Channels and provider setup: Web Chat channels, provider credentials and how replies leave each channel.
- Workspaces, roles and routing: workspaces, roles and why a key’s workspaces matter.
- Console and admin reference: every Admin Settings section.
- Operations and troubleshooting: workers, monitoring and retention.