Webhooks

Subscribe to ticket events and receive HTTP POST notifications to your server when things happen in DeskFork.

Adding a webhook

Settings → Developers → Webhooks → Add webhook

Field	Description
URL	HTTPS endpoint on your server
Events	Which events to subscribe to
Secret	Used to sign deliveries (auto-generated)

Verifying signatures

Each delivery includes a signature header:

X-DeskFork-Signature: sha256=<hex-digest>

Verify with HMAC-SHA256:

import { createHmac } from "node:crypto";

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return `sha256=${expected}` === signature;
}

Event payload structure

{
  "id": "evt_01j9abc123",
  "type": "ticket.created",
  "created_at": "2026-06-28T10:00:00Z",
  "workspace": "acme",
  "data": {
    "ticket": {
      "id": "TKT-0042",
      "subject": "Order not received",
      "status": "open",
      "channel": "email",
      "contact": { "email": "customer@deskfork.com", "name": "Jane Doe" }
    }
  }
}

Event types

Event	Fired when
`ticket.created`	New ticket created (any channel)
`ticket.assigned`	Assignee added or changed
`ticket.status_changed`	Status transition (open → pending → resolved → closed)
`ticket.tagged`	Tag added or removed
`message.created`	Reply or internal note added
`sla.warning`	SLA deadline is approaching (< 20% time remaining)
`sla.breached`	SLA target missed
`contact.created`	New contact record created
`contact.updated`	Contact fields updated

Retry policy

Failed deliveries (non-2xx) are retried with exponential backoff:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours

After 5 failures the webhook is marked degraded and paused. Re-enable it under Settings → Developers → Webhooks.

Idempotency

Each event has a unique id. Your endpoint should store processed event IDs and skip duplicates to handle retries safely.