Integrations
SupportDesk integrates with external systems through scoped API clients, outbound webhooks, inbound mailbox payloads, and update delivery endpoints.
API Clients
Admins create API clients at /integrations/api-clients. Each client has a name, active state, token prefix, hashed token, last-used metadata, and scopes. Plain tokens are only shown when created or rotated, so store them immediately.
API Authentication
External clients authenticate with either an Authorization bearer token or X-Api-Key. Tokens are generated with a tpk_ prefix and stored as SHA-256 hashes.
Authorization: Bearer tpk_your_token_here
X-Api-Key: tpk_your_token_hereAPI Scopes
| Scope | Purpose |
|---|---|
tickets.read | Read tickets, lookups, and suggestions. |
tickets.write | Create or update tickets and internal notes. |
tickets.reply | Add customer-facing replies. |
tickets.attachments | Upload and download ticket attachments. |
tickets.transitions | Move ticket status through transition endpoint. |
tickets.bulk | Apply bulk ticket changes. |
webhooks.read | Read webhook delivery records. |
webhooks.write | Replay deliveries and receive inbound sync updates. |
Webhooks
Webhook subscriptions have name, connector type, endpoint URL, optional secret, event list, delivery profile, active state, last delivery time, and last delivery status. Connector types include generic, Slack, Teams, HRIS, CRM, payroll, and SIEM.
Webhook Events
Subscriptions can listen to * or specific ticket events such as ticket created, assigned, reassigned, status updated, replied, SLA warning, communication approval events, assigned down, and returned to lead.
Webhook Signature
If a secret is configured, outbound webhooks include X-SupportDesk-Signature, which is an HMAC SHA-256 hash of the JSON body using the subscription secret. Webhooks also send X-SupportDesk-Event and X-SupportDesk-Ticket.
Inbound Mailboxes
Mailboxes accept inbound messages at /api/v1/mailboxes/{mailboxKey}/inbound. The request must include X-SupportDesk-Mailbox-Token. Payload fields include from email, from name, subject, text body, HTML body, in-reply-to, references, and attachments.
Monitoring
The Operations Center shows active API clients, active webhooks, webhook failures, delivery logs, mailboxes, and heartbeats. Failed webhook deliveries can be replayed from Platform Ops or through the API when the client has webhooks.write.
Screenshots To Add
These placeholders are intentionally kept in the docs so release screenshots can be dropped in later without changing the written guide for Integrations.