Webhooks

Souscrivez aux événements budget, Guardian, paiement, rotation de clé, et compte. Payloads signés avec retry.

HiWay peut POSTer des événements à votre endpoint en temps réel, Guardian qui se déclenche, seuils budget franchis, échecs de paiement, clés API rotées, balance compte basse. Configurez un ou plusieurs webhooks par workspace, filtrez optionnellement par type d'événement, et vérifiez les payloads avec un secret partagé.

Événements disponibles

Événement	Déclenché quand	Le payload contient
`guardian.block`	Une règle Guardian bloque ou ralentit une requête.	nom de la règle, workspace, clé, hash de la requête, action prise
`budget.alert`	Budget Control franchit un seuil de verdict (warn / downgrade / block).	cap, dépensé, verdict, date de reset
`payment.succeeded`	Un top-up Stripe ou facture d'abonnement est payée.	montant, devise, ID facture, nouveau solde wallet
`payment.failed`	Stripe remonte `invoice.payment_failed`.	montant, devise, code échec, nombre de tentatives
`key.rotated`	Une clé API est rotée ou révoquée.	key ID, préfixe clé, rotated_at
`account.low_balance`	La balance wallet franchit 20%, 10% ou 0% du dernier top-up.	balance, last_topup, palier % (20/10/0)
`security.event` (Security Shield)	Menace détectée en mode `monitor` ou `block` (voir doc SIEM Security Shield).	threat_type, score, action, req_id, hash du prompt

Configurer un webhook

curl -X POST https://app.hiway2llm.com/api/v1/workspaces/WS_ID/webhooks \
  -H "Authorization: Bearer hw_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":   "Alertes prod",
    "url":    "https://your-app.example.com/hooks/hiway",
    "secret": "whsec_remplacer_par_secret_long_aleatoire",
    "events": ["guardian.block", "budget.alert", "account.low_balance"]
  }'

Omettez events pour recevoir tous les types. Passez une liste vide pour pauser la livraison sans supprimer le webhook.

Format du payload

json

{
  "event":        "guardian.block",
  "workspace_id": "01HXYZ...",
  "timestamp":    "2026-05-29T10:30:00Z",
  "data": {
    "rule":          "context_bloat",
    "key_id":        "kid_abc123",
    "request_hash":  "sha256:...",
    "action":        "blocked",
    "threshold":     200000,
    "observed":      234567
  }
}

Vérification de signature

Chaque requête inclut un header X-HiWay-Signature calculé à partir du secret partagé que vous avez configuré. Vérifiez-le avant de traiter, protégez votre endpoint contre la forgerie.

import crypto from "node:crypto";

function verify(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader),
  );
}

Utilisez le corps brut

Calculez la signature sur les octets exacts du corps de la requête, avant toute re-sérialisation JSON. Les frameworks qui parsent le JSON avant d'exposer le body peuvent silencieusement reformater les espaces et casser la signature.

Sémantique de retry & livraison

Timeout : 5 secondes par tentative de livraison.
Retry sur 5xx, 408, 429, ou erreur de connexion. Backoff exponentiel : 1s, 5s, 30s, 5min, 30min (5 tentatives max).
Pas de retry : 2xx, 3xx (compté succès), 4xx (sauf 408/429, compté comme erreur config client, pas de retry).
Chaque retry inclut le même event_id pour l'idempotence. Traitez les réceptions en at-least-once.
Après 5 tentatives échouées, le webhook est marqué stale et un événement webhook.stale est envoyé à vos autres webhooks (s'il y en a) pour ne pas vous laisser silencieux.

Monitoring de livraison

Chaque webhook trace last_fired_at et last_status (le code HTTP de la dernière réponse de votre endpoint). Visibles dans Dashboard → Settings → Webhooks. Si last_status affiche systématiquement du 4xx, corrigez votre auth/endpoint. Si last_status = 0, votre endpoint est inaccessible (DNS, TLS, firewall).