vicket
Get started
API / Nº 04

Webhooks

Webhooks are outbound HTTPS POSTs we send to your endpoints when interesting things happen. They are fired by workflows through the send_to_connector action with a webhook connector, never directly by API calls. This means you can route, filter, and rate-shape them with the same rules as any other automation.

Payload

Every webhook POST has the same envelope:

{
  "id": "9f2c1b7e-...",
  "event": "ticket.status_changed",
  "occurred_at": "2026-05-23T14:21:11.412Z",
  "data": {
    "ticket": { "id": "...", "status": { "category": "resolved" } },
    "message": "Ticket resolved by the on-call agent."
  }
}
  • id: globally unique, stable. Use it for idempotency.
  • event: the workflow trigger that fired (see workflows).
  • occurred_at: RFC 3339 timestamp of when the source event happened, not the delivery attempt.
  • data: event payload plus the message configured on the action.

Signature verification

Every request carries an X-Vicket-Signature header containing an HMAC-SHA256 of the raw request body, signed with the secret you set when configuring the webhook connector.

X-Vicket-Signature: hmac-sha256, t=1716475271, v1=4f9c8e2b7a...

Compute the signature on your end and compare in constant time:

import { createHmac, timingSafeEqual } from "node:crypto";

const expected = createHmac("sha256", process.env.VICKET_WEBHOOK_SECRET!)
  .update(rawBody)
  .digest("hex");

const sigHex = header.split("v1=")[1];
if (!timingSafeEqual(Buffer.from(sigHex, "hex"), Buffer.from(expected, "hex"))) {
  return new Response("invalid signature", { status: 401 });
}

The t= parameter is a unix timestamp. Reject requests where |now - t| > 300s to prevent replay.

Idempotency

Webhook delivery is at-least-once. The same id may arrive twice if your endpoint returned a non-2xx response or timed out. Store the id the first time you see it and short-circuit subsequent deliveries.

Retries

Non-2xx responses (or no response within 10s) are retried with exponential backoff. Failed deliveries are surfaced in the workflow's run history with the raw response body for debugging.

Next