Webhooks push events to your endpoint as they happen. Admins add them in Admin → Webhooks, choose the events and get a signing secret. Each delivery is an HTTP POST with a JSON body:
{
"event": "ticket.created",
"occurredAt": "2026-03-02T10:00:00.412Z",
"data": {
"id": "…",
"ref": "INC-1042",
"subject": "VPN disconnects every hour",
"status": "OPEN",
"…": "…"
}
}
| Event | When |
|---|
| ticket.created | Ticket created |
| ticket.updated | Ticket updated |
| ticket.resolved | Ticket resolved |
| ticket.closed | Ticket closed |
| ticket.reply | Reply added to a ticket |
| problem.created | Problem created |
| change.created | Change created |
| change.updated | Change updated |
| asset.created | Asset created |
| asset.updated | Asset updated |
data is the record in the same shape the API returns (ticket.reply carries { ticket, message }). Headers:
X-Webhook-Event: the event name.X-Webhook-Delivery: the delivery id, unchanged across retries.X-Webhook-Signature: sha256= followed by the hex HMAC-SHA256 of the raw body, keyed with the webhook's secret.User-Agent: Arvesk-Webhooks/1.0.
Answer with any 2xx status within 10 seconds. Anything else (an error status, a redirect, a timeout) is retried with exponential backoff (30 seconds, 2 minutes, 8 minutes, 32 minutes, 1 hour) and given up after 6 attempts. Delivery is at least once, so de-duplicate on X-Webhook-Delivery. Verify the signature before trusting a payload:
import { createHmac, timingSafeEqual } from "node:crypto";
import express from "express";
const app = express();
// Verify against the raw body: re-serialising parsed JSON changes the bytes.
app.post("/webhooks/helpdesk", express.raw({ type: "application/json" }), (req, res) => {
const expected = "sha256=" + createHmac("sha256", process.env.WEBHOOK_SECRET).update(req.body).digest("hex");
const given = req.get("X-Webhook-Signature") ?? "";
const ok = given.length === expected.length && timingSafeEqual(Buffer.from(given), Buffer.from(expected));
if (!ok) return res.status(401).send("bad signature");
const deliveryId = req.get("X-Webhook-Delivery"); // stable across retries, use it to de-duplicate
const { event, occurredAt, data } = JSON.parse(req.body.toString("utf8"));
// …queue the work, then answer quickly
res.sendStatus(204);
});