Webhooks

The Webhook integration sends a request to your own web address every time something happens to a ticket — a ticket is created, closed, reopened, assigned, escalated, rated, and more. Your system receives the event and can do whatever you like with it: log it, sync it to a CRM, post it somewhere, or kick off an automation.

You need somewhere to receive the events — a URL your team controls. Everything on the Clarify side is point-and-click, and it costs no feature token.

How it works

When a selected event happens, Clarify sends an HTTPS POST to your URL with the event and the ticket in the body. Every request is signed with your secret, so your server can confirm it came from Clarify and was not altered on the way. Clarify tries up to three times (10 seconds each, with a short pause between attempts) before giving up on a delivery.

Requests are sent through Clarify's delivery relay, so do not filter by IP address — verify the signature instead.

Destination

Events

The X-Clarify-Event header and event.type in the body carry the event name: created, opened, closed, assigned, unassigned, added, removed, rated, escalated.

Custom headers

What a request looks like

POST /hooks/clarify HTTP/1.1
Content-Type: application/json
X-Clarify-Event: closed
X-Clarify-Timestamp: 1758000000
X-Clarify-Signature: sha256=3f7a…

{
  "event": {
    "type": "closed",
    "timestamp": 1758000000000,
    "serverId": "123456789012345678",
    "ticketId": "…",
    "executor": { "id": "…", "username": "alex", "avatarUrl": "…" }
  },
  "ticket": { "…": "the full ticket record — participants, messages, inputs, assignees, routing" },
  "review": null
}

• event.timestamp is in milliseconds; the X-Clarify-Timestamp header is in seconds.
• ticket is the complete ticket as Clarify stores it, including its messages and the answers to its inputs. Treat your endpoint as confidential as the tickets themselves.
• review holds the customer's rating and comment once the ticket has been rated, on every later event too; before that it is null.

Verifying the signature

Clarify signs "<X-Clarify-Timestamp>.<raw request body>" with HMAC-SHA256 using your secret and sends the hex digest as X-Clarify-Signature: sha256=…. Recreate it and compare:

import { createHmac, timingSafeEqual } from 'node:crypto'

function verify(rawBody, headers, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret)
    .update(`${headers['x-clarify-timestamp']}.${rawBody}`)
    .digest('hex')
  const given = headers['x-clarify-signature'] ?? ''
  return given.length === expected.length && timingSafeEqual(Buffer.from(given), Buffer.from(expected))
}

Use the raw body bytes, not a re-serialised object. Reject requests whose timestamp is far from now if you want protection against replays.

Turning it on and testing

Related