# 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.

```javascript
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](https://github.com/hookdeck/webhook-skills/blob/main/skills/tokity-webhooks/references/verification.md).

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/tokity-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/tokity-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/tokity-webhooks/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

```bash
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

```bash
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](https://github.com/hookdeck/webhook-skills/blob/main/skills/tokity-webhooks/references/overview.md) - Webhooks vs. Events, ticket and chat payloads
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/tokity-webhooks/references/setup.md) - Creating a webhook and finding its secret in the Admin Portal
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/tokity-webhooks/references/verification.md) - Signature details in Node, Python and Next.js, gotchas
* [examples/](https://github.com/hookdeck/webhook-skills/tree/main/skills/tokity-webhooks/examples/) - Runnable Express, Next.js and FastAPI handlers with tests