Guide to Tokity Webhooks: Features and Best Practices
Tokity, formerly DeskDirector, adds client and technician portals on top of PSA ticketing systems such as ConnectWise and Autotask. Its webhooks tell other systems when a ticket changes or a chat session moves on, which MSPs use to post to Teams or Slack, chase approvals or follow up on missed chats.
This guide covers Tokity's two notification mechanisms, how to tell what changed when the body names no event, verifying x-dd-signature, and what isn't documented about delivery.
What are Tokity webhooks?
Tokity offers two ways to be notified about ticket changes, and both sign their requests the same way:
| Webhooks | Events | |
|---|---|---|
| Setup | Admin Portal > Advanced > Webhook | Admin Portal event editor (or indirectly via the Power Automate connector) |
| Filtering | Choose the ticket change types to subscribe to; filter the rest yourself | Trigger + conditions (queue, priority, tags...) + one or more actions |
| Payload | Ticket plus from (previous state) | Simpler: no from, because Tokity filtered on state first |
| History | None | 28-day run history with per-action delivery results |
| Limit | None documented | 100 events per tenant |
Tokity recommends Events where your plan includes them. Webhooks remain for lower subscription tiers and for tenants that have reached the 100-event limit. A Power Automate flow built with the DeskDirector connector creates an event behind the scenes and counts towards that limit.
Tokity webhook features
| Feature | Details |
|---|---|
| Signature | base64 HMAC-SHA256 |
| Signature header | x-dd-signature |
| Body | JSON |
From Tokity's data sync notifications article and webhooks article:
- Each webhook registration, and each event, has its own auto-generated secret.
- A slider beside the Webhook header turns all of a site's webhooks on or off.
- The Payload Sample tab shows a sample payload and JSON schema, which Zapier and Power Automate can use.
- Tokity sends changes as they happen rather than batching them.
Events and payloads
No header or body field says which change happened. You pick the change types when you register the webhook, so a narrow subscription tells you what a request means. The ticket change types are Ticket created, Status changed, Ticket updated (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. Chat webhooks fire when a session is created or updated.
Ticket Webhook Payload
fromisnull: the ticket did not exist before, so this is a ticket-created delivery.fromis an object: diff it against the current ticket data to see what changed.- The body is wrapped in an array for historical reasons (batching was planned). Expect one item
The ticket fields themselves aren't published outside the Admin Portal, so copy the schema from the Payload Sample tab. An Events action sends the ticket without from.
Chat Session Payload
| Field | Meaning |
|---|---|
id, name | Session id and name |
status | created, handled (by a technician), missed (user left unanswered), callback (user left a callback request) or completed |
pastStatus | List of earlier statuses |
type | request (from the end user, in a portal) or push (started by an agent in the TECH Portal) |
reference | If the chat is about a ticket: { "type": "ticket", "id": "<ticket id>" } |
creator | Who created the session (a member or a contact) |
targetUsers, users, participants | Invited users, users currently in the chat, everyone who ever joined |
createdDateTime, lastModifiedDateTime | Timestamps |
The article's field list calls the last list partitions, but the example and JSON schema both use participants. A trimmed chat example from the webhooks article:
[
{
"msp": "dd",
"id": "1586985009-627B",
"name": "Test",
"type": "request",
"status": "handled",
"pastStatus": ["created", "handled"],
"reference": { "type": "ticket", "id": "22282" },
"creator": { "entityId": 106, "name": "Jason He", "userId": "dd~c~106" },
"lastModifiedDateTime": "2020-04-15T21:12:00.9897216Z"
}
]
Setting up Tokity webhooks
- In the Admin Portal, go to Advanced > Webhook and check that the slider beside the header is on.
- Choose Create Webhook > Add ticket/chat/custom webhook.
- Enter a Description and the Receiver URL, for example
https://example.com/webhooks/tokity. - Select the ticket change types or chat events to listen for.
- On Registered Webhooks, click Display detail to see the secret, and store it as
TOKITY_WEBHOOK_SECRET. - Trigger the change, for example by commenting on a ticket, to test it.
For an Event instead, build the trigger and conditions in the event editor and add your URL as an action. The event has its own secret.
Each webhook registration (and each event) gets its own auto-generated secret, shown with "Display detail" and regenerable; used as UTF-8 bytes.
To route through Hookdeck, create a Tokity source with that secret and use its URL as the receiver URL. For local development:
npx hookdeck-cli listen 3000 tokity --path /webhooks/tokity
Securing Tokity webhooks
x-dd-signature is sha256= followed by the standard base64 HMAC-SHA256 of the raw body, keyed with the secret's UTF-8 bytes. Tokity's C# sample builds the value with Convert.ToBase64String and compares strings, so the digest is base64, not hex. Use the secret exactly as shown, without decoding it.
Node.js verification
const crypto = require('node:crypto');
function decodeBase64(value) {
if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
const bytes = Buffer.from(value, 'base64');
return bytes.length > 0 && bytes.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
? bytes : null;
}
function verifySignature(rawBody, headers, secret) {
if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
const signature = headers['x-dd-signature'];
if (typeof signature !== 'string') return false;
const key = Buffer.from(secret, 'utf8');
const message = rawBody;
const candidates = [signature.startsWith('sha256=') ? signature.slice(7) : signature];
const expected = crypto.createHmac('sha256', key).update(message).digest();
return candidates.some((candidate) => {
const received = decodeBase64(candidate);
if (!received) return false;
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
Tokity's bodies carry no delivery ID, so the handler uses a hash of the raw body as its deduplication key. It accepts only an array and skips items that aren't objects.
const crypto = require('node:crypto');
const express = require('express');
const app = express();
app.post('/webhooks/tokity', express.raw({ type: '*/*' }), async (req, res) => {
const secret = process.env.TOKITY_WEBHOOK_SECRET;
if (!secret) return res.sendStatus(500);
if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
let items;
try {
items = JSON.parse(req.body.toString('utf8'));
} catch {
return res.sendStatus(400);
}
if (!Array.isArray(items)) return res.sendStatus(400);
const changes = items.filter((item) => item && typeof item === 'object' && !Array.isArray(item));
const deliveryKey = crypto.createHash('sha256').update(req.body).digest('hex');
try {
if (await alreadyHandled(deliveryKey)) return res.sendStatus(200);
for (const change of changes) {
const kind = 'from' in change ? (change.from === null ? 'ticket.created' : 'ticket.changed') : 'other';
await queue.add('tokity-change', { kind, change });
}
await markHandled(deliveryKey);
} catch {
return res.sendStatus(503);
}
res.sendStatus(200);
});
Give each subscription its own path if you subscribe to several change types, since the body won't say which one fired. Replace queue, alreadyHandled and markHandled with your own job queue and deduplication store.
A Hookdeck Tokity source verifies requests the same way. It returns 200 and records any mismatch as failed verification. Nothing time-based is signed by Tokity, and Hookdeck sets no age limit.
Make Tokity webhooks production-ready. Hookdeck Event Gateway gives plain webhooks the delivery history that only Tokity Events have, and retries your service when it's down.
Tokity webhook limitations and pain points
No event type on the wire
The Problem: A request doesn't say whether it's a comment, a status change or an approval.
Why It Happens: Tokity treats the change type as a subscription choice, not a payload field.
Workarounds:
- Register one webhook per change type, each with its own URL path.
- Or subscribe to Ticket updated and diff
fromagainst the current ticket.
How Hookdeck Can Help: Separate Hookdeck sources, one per subscription, label each request by where it arrived, and transformations can add a type field before delivery.
Webhooks have no delivery history
The Problem: You can't see which webhook calls succeeded.
Why It Happens: Tokity keeps a 28-day run history for Events only. A webhook appears under Deleted Webhooks if it keeps failing outright, with no per-call log.
Workarounds:
- Use Events where your plan allows.
- Log every request on your side, and check Deleted Webhooks if deliveries stop.
How Hookdeck Can Help: Hookdeck records each request and each attempt to your service, and answers Tokity quickly so failures on your side don't count against the webhook.
Delivery behaviour is undocumented
The Problem: You don't know whether Tokity retries, how long it waits, or which status codes count as success.
Why It Happens: Tokity's articles don't describe retries, timeouts or success codes.
Workarounds:
- Respond with
200as soon as the change is queued. - Reconcile tickets against your PSA periodically.
How Hookdeck Can Help: Hookdeck stores each delivery and retries your service under a policy you set.
Ticket schema is only in the Admin Portal
The Problem: You can't write a ticket parser from public documentation.
Why It Happens: Only the chat payload is published. The ticket schema and example sit in the Payload Sample tab.
Workarounds:
- Copy the schema from the Payload Sample tab into your tests.
- Capture a real delivery for each change type you use.
How Hookdeck Can Help: Hookdeck keeps every delivered body for you to inspect and replay.
Best practices
Prefer Events for filtering
Conditions in Tokity filter by queue, priority and tags before anything is sent. If you're near the 100-event limit, merge events that differ only by one condition value into a single event with a multi-value condition.
Subscribe narrowly
One change type per webhook makes each request self-describing and saves diffing.
Deduplicate without an ID
Hash the raw body or build a key from the ticket ID and its modified time. The idempotency guide covers storage options.
Handle the array
Loop over the array even though it usually holds one item, as Tokity keeps the format for possible future batching.
Conclusion
Tokity sends ticket and chat changes as JSON arrays signed with sha256= plus a base64 HMAC-SHA256 in x-dd-signature. The body never names the change type, so subscribe narrowly or diff from, and plan your own logging and retries, since plain webhooks have no history and the delivery policy isn't published.
Hookdeck Event Gateway verifies Tokity requests, keeps a record of each one and retries delivery to your systems.
Get started with Hookdeck for free and handle Tokity webhooks reliably in minutes.