Webhooks
Les webhooks sont des POST HTTPS sortants que nous envoyons vers vos endpoints quand quelque chose d'intéressant se produit. Ils sont déclenchés par les workflows via l'action send_to_connector avec un connecteur webhook, jamais directement par les appels API. Vous pouvez donc les router, les filtrer et les limiter avec les mêmes règles que n'importe quelle automatisation.
Payload
Chaque POST de webhook a la même enveloppe :
{
"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: unique et stable. Utilisez-le pour l'idempotence.event: le déclencheur de workflow qui a tiré (voir workflows).occurred_at: timestamp RFC 3339 de l'événement source, pas de la tentative de livraison.data: le payload de l'événement plus le message configuré sur l'action.
Vérification de signature
Chaque requête porte un en-tête X-Vicket-Signature contenant un HMAC-SHA256 du corps brut, signé avec le secret défini à la configuration du connecteur webhook.
X-Vicket-Signature: hmac-sha256, t=1716475271, v1=4f9c8e2b7a...
Calculez la signature de votre côté et comparez en temps constant :
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 });
}
Le paramètre t= est un timestamp unix. Rejetez les requêtes où |now - t| > 300s pour empêcher le replay.
Idempotence
La livraison est at-least-once. Le même id peut arriver deux fois si votre endpoint a répondu hors 2xx ou expiré. Stockez l'id à la première occurrence et court-circuitez les livraisons suivantes.
Réessais
Les réponses hors 2xx (ou l'absence de réponse sous 10 s) sont réessayées avec un backoff exponentiel. Les livraisons en échec apparaissent dans l'historique des runs du workflow avec le corps de réponse brut pour le debug.