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-signature header?
  • Why does my Tokity webhook endpoint return 401?
  • How do I tell what changed on a ticket from a Tokity webhook (the from property)?
  • 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:

KindBodyHow to tell
ticket_changeTicket 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.
chatAn 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


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 17, 2026

View on GitHub →