URL safety
Destination checks
Kantan Desk checks webhook destinations at setup and delivery time, blocks private/internal destinations, pins the connection to the checked address, refuses redirects, and times out slow requests.
Integrations
Controlled entry points for support automation.
Kantan Desk can accept tickets from external systems and send signed ticket events to workflow tools, while keeping credentials scoped, signed, and reviewable.
Inbound ticket API
Create tickets from systems, not just people.
Only a SuperAdmin can create an API key. The key is narrow: the supported permission is currently ticket:create, and team assignment, IP allowlist, and HMAC signing are mandatory.
| Endpoint | POST /api/v1/ticket/public/create |
|---|---|
| Headers | X-API-Key, X-KD-Timestamp, and X-KD-Signature. |
| Signature | v1=<hex HMAC-SHA256> over <timestamp>.<exact raw body>. |
| Replay window | The timestamp must be within five minutes; a previously accepted timestamp/body/signature cannot be replayed in that window. |
| Source policy | API keys can be typed as api, webhook, cli, or monitoring. Payload source must match the key type when supplied. |
| Failure classes | Invalid input returns 400; missing, invalid, stale, or replayed credentials return 401; permission, team, integration type, or IP policy failures return 403; rate limits return 429. |
Accepted ticket fields
The API intentionally keeps the writable ticket surface small.
| Field | Accepted value |
|---|---|
title | Required string, 1-500 characters. |
detail | Optional string or null, up to 50,000 characters. |
priority | low, medium, or high; defaults to low. |
type | Defaults to support; supported values include bug, feature, support, incident, service, maintenance, access, feedback, general enquiry, sales, accounts, technical, and GDPR/legal. |
email and name | Optional requester identity fields, with email validated where present. |
| Not accepted | API callers cannot set company, engineer, or createdBy. Kantan Desk supplies the team and records the API key as creator. |
Automation and monitoring
Scripts, monitors, and alerts feed directly into the queue.
Dedicated key types for monitoring systems and CLI scripts mean external automation can create and attribute tickets without sharing a generic API key. Each source is identified separately so automated work is distinct from customer requests.
- CLI keys are designed for custom scripts, deployment tools, and scheduled automation — any process that needs to open a ticket as part of its own workflow.
- Monitoring keys are purpose-built for uptime monitors, infrastructure agents, and alerting platforms; tickets are attributed to the monitoring source automatically.
- Route script-created and alert tickets to separate on-call teams using default assignment rules, keeping automated work distinct from customer queues.
- Set ticket priority to reflect alert severity or script outcome and track time to acknowledgement and resolution alongside other work.
- HMAC request signing verifies every submission originates from an authorised source; outbound webhooks notify external systems when automation tickets are updated or closed.
Outbound webhooks
Signed events for external workflows.
Users with webhook::create can create webhooks for ticket-created and ticket-status-changed events, with optional team scope.
- Each webhook receives a one-time secret that should be copied into the receiver’s secrets store.
- Deliveries use
X-KantanDesk-Signature-Version: v2andX-KantanDesk-Signature: v2=<hex HMAC-SHA256>. - The signed value is
<timestamp>.<exact raw request body>. - Receivers should verify raw bytes before JSON parsing, require the delivery ID, enforce a short timestamp window, compare signatures in constant time, and reject repeated delivery IDs.
- Failed queued deliveries are attempted up to three times with exponential backoff and keep the same delivery ID.
Payloads
Ticket event data
Generic receivers get a data wrapper with event, title, priority, requester, creator, assignee, and client fields. Status-change events add newStatus.
Discord
Special payload shape
Discord URLs receive Discord’s embeds shape instead of the generic wrapper, while still using the v2 signature over the exact transmitted bytes.
Email integrations
Email is an integration path too.
Kantan Desk’s mailbox layer connects support work to existing email infrastructure.
- Inbound messages are fetched from active IMAP mailboxes.
- Gmail OAuth is supported for Gmail mailbox access.
- Per-mailbox SMTP sends reply-bearing ticket email.
- A separate system SMTP relay sends account email and one-way notifications.
- Mail-service reputation hooks can update bounced or complained addresses for system-relay sends.
API rotation
Rotate HMAC and update callers immediately.
API keys use “Save and Rotate HMAC.” The new value is displayed once, and there is no dual-secret grace period.
Webhook rotation
Deactivate, rotate, test, reactivate.
Webhook secret rotation invalidates the previous secret immediately. Receivers should be updated with the newly displayed secret before testing or resuming deliveries.