Agent skill
Tokity Webhooks Skill
Receive and verify Tokity (formerly DeskDirector) webhooks. Use when setting up a Tokity webhook or Events action receiver, verifying the x-dd-signature HMAC-SHA256 header, debugging 401 signature failures, or handling ticket change and chat session payloads from the Tokity PSA portal.
Install this skill
npx skills add hookdeck/webhook-skills --skill tokity-webhooks
Tokity (tokity.com, formerly DeskDirector) puts client and tech portals on top of PSA ticketing (ConnectWise, Autotask and others). It POSTs a signed JSON payload whenever a ticket changes or a chat session is created or updated. Both webhooks and Events actions sign every request with HMAC-SHA256 in the x-dd-signature header, using a secret unique to that webhook or event.
When to Use This Skill
- How do I receive Tokity (DeskDirector) webhooks?
- How do I verify the Tokity
x-dd-signatureheader? - Why does my Tokity webhook endpoint return 401?
- How do I tell what changed on a ticket from a Tokity webhook (the
fromproperty)? - How do I handle Tokity chat session webhooks?
Verification (core)
x-dd-signature: sha256=<base64> where the base64 is the standard, padded HMAC-SHA256 of the raw request body bytes, keyed with the webhook's secret as UTF-8 text (not hex- or base64-decoded). Nothing else is signed: no timestamp, no id.
const crypto = require('crypto');
const BASE64_SHA256 = /^[A-Za-z0-9+/]{43}=$/; // exactly 44 chars, padded standard base64
function verifyTokitySignature(rawBody, header, secret = process.env.TOKITY_WEBHOOK_SECRET) {
if (!secret || typeof header !== 'string' || !Buffer.isBuffer(rawBody)) return false;
const received = header.startsWith('sha256=') ? header.slice(7) : header; // bare digest also ok
if (!BASE64_SHA256.test(received)) return false;
const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('base64');
const a = Buffer.from(received), b = Buffer.from(expected); // compare the strings, don't decode
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
Return 401 for a missing, empty or malformed header, or a mismatch. Read the body as bytes (express.raw({ type: '*/*' }), await request.arrayBuffer(), await request.body()) and parse JSON only afterwards. Compare the base64 text rather than decoding it: a decoder also accepts bad characters and a non-canonical last character that Tokity's own check would reject. Python and Next.js versions are in references/verification.md.
For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.
Payloads and Event Types
There is no event-name field or header. You choose the ticket change types a webhook fires for when you register it, but the request does not say which one fired. Work it out from the body:
| Kind | Body | How to tell |
|---|---|---|
ticket_change | Ticket fields plus from: the ticket's previous state. Wrapped in an array with one item in practice. | from is null on creation; otherwise diff from against the current fields. An Events action sends the ticket without from. |
chat | An array of chat sessions (id, status, pastStatus, type, reference, creator, users...). | status is one of created, handled, missed, callback, completed. |
ticket_change and chat are labels used in this skill's examples, not Tokity event names. The change types you can subscribe a ticket webhook to are: Ticket created, Status changed, Ticket updated (fires on any change), Comment added, Ticket closed, Ticket re-opened, Time entry added, Approval required, Approval granted, More info requested, Ticket survey response received, Ticket tags updated and Ticket survey triggered.
Treat every field of the parsed body as untrusted: check the type of the body and of each nested field before reading it, so a wrong-typed value is ignored or answered with 400, never a 500.
Delivery
Tokity's docs do not document retries, the delivery timeout or which response codes count as success. Return 200 quickly and make handling idempotent. Events keep a 28-day run history with per-action delivery results; webhooks keep none.
Environment Variables
TOKITY_WEBHOOK_SECRET=kfA18wgZKW30F7dL1JtlHq2judcJ0uoB # from "Display detail" on the webhook
Each webhook registration (and each event) has its own secret, so a receiver serving several of them needs the matching secret for each route.
Local Development
npx hookdeck-cli listen 3000 tokity --path /webhooks/tokity
No account required. Use the printed URL as the Receiver URL in the Tokity Admin Portal. Hookdeck's Tokity source verifies the signature using the same secret.
Resources
- references/overview.md - Webhooks vs. Events, ticket and chat payloads
- references/setup.md - Creating a webhook and finding its secret in the Admin Portal
- references/verification.md - Signature details in Node, Python and Next.js, gotchas
- examples/ - Runnable Express, Next.js and FastAPI handlers with tests