Skip to main content
Quand l’agent Actero termine un ticket, escalade un cas, ou détecte un sentiment critique, tu peux recevoir l’événement en temps réel sur ton propre serveur via un webhook sortant. Chaque livraison est signée HMAC-SHA256 pour que tu puisses vérifier l’origine.
Les webhooks sortants sont une feature plan Pro et plus. Sur Free et Starter, tu peux toujours pull la donnée via /api/billing/usage ou les API admin du dashboard.

Configuration

Dashboard → API & Intégrations → Webhooks → Nouveau webhook. À la création, Actero génère un secret au format whsec_ + 48 caractères hex. Stocke-le côté ton serveur — il sert à vérifier la signature.

Événements disponibles

Voir Escalades pour le contexte métier de ticket.escalated, et Manual review pour le workflow de validation humaine en aval.

Format de la requête

Actero POST vers ton URL avec ces headers et ce body :
Le contenu de data dépend de l’événement. Code défensivement : on peut ajouter des champs sans préavis.

Vérifier la signature

X-Actero-Signature contient v1=<hex><hex> est le HMAC-SHA256 de la chaîne <timestamp>.<raw_body> calculée avec ton secret.
Compare toujours en temps constant (crypto.timingSafeEqual / hmac.compare_digest). Une comparaison === classique fuit la longueur du préfixe correct via timing.

Réponse attendue

Le retry automatique n’est pas encore implémenté. Si tu manques une livraison, rejoue-la depuis Dashboard → Webhooks → Livraisons (50 dernières conservées par webhook).
Après 20 échecs consécutifs, le webhook est désactivé automatiquement (is_active = false). Un email est envoyé à l’owner du tenant.

Idempotence

Actero n’envoie pas le même événement deux fois pour un même event_id métier. Néanmoins, en cas de bug réseau, ton serveur peut recevoir deux POST. Dédupliquer côté ton handler par (event, data.ticket_id) est une bonne pratique.

Rate limit

Pas de rate limit côté webhook : si un client génère 200 tickets/heure (le maximum sur l’engine), ton endpoint reçoit 200 POST/heure. Prévois ton infra en conséquence.

Tester en local

Le dashboard expose un bouton Tester qui envoie un payload ticket.resolved factice à ton URL. Combine avec ngrok ou smee.io pour développer en local.

Limites

  • 1 secret par webhook. Pour rotater : crée le nouveau, déploie, supprime l’ancien.
  • 50 livraisons conservées par webhook (rolling). Au-delà, archive côté ton infra.
  • Le body peut atteindre ~50 KB sur un ticket.resolved chargé en historique. Configure ton serveur pour accepter au moins 100 KB.