Webhooks

Un webhook prévient un outil tiers en temps réel : Actero envoie un POST à l’adresse que tu donnes, à chaque événement choisi. Chaque envoi est signé HMAC-SHA256 pour que tu puisses vérifier qu’il vient bien d’Actero.

Les webhooks sont disponibles dès le plan Starter, pour la personne propriétaire et les managers de la boutique.

Configuration

Dashboard → IA et API → Les webhooks → Ajouter un webhook.

Champ	Description
Nom	Nom interne (ex. `Zapier`, `CRM`). 100 caractères au plus.
Adresse	Adresse `https://` sur un hôte public. Elle doit répondre `2xx` en moins de 5 s.
Événements	Au moins un des trois événements ci-dessous.

À la création, Actero génère un secret au format whsec_…, affiché une seule fois : garde-le côté ton serveur, il sert à vérifier la signature. Une boutique peut avoir 10 webhooks. « Envoyer un test » envoie un événement test.ping signé ; la page montre les 20 derniers envois.

Événements disponibles

Seuls les événements qu’Actero envoie vraiment sont proposés.

ID	Envoyé quand…
`ticket.escalated`	L’agent passe la main à ton équipe : la demande arrive dans « À traiter ».
`ticket.resolved`	L’agent a répondu seul à un message (un envoi par message, pas par conversation).
`conversation.created`	Un client écrit pour la première fois : bulle, e-mail, Zendesk ou Gorgias.

Rien ne part pour le test de démarrage. « Tester mon agent » étant réel, ses conversations envoient les mêmes événements qu’un vrai client. Voir Escalades pour le contexte métier de ticket.escalated.

Format de la requête

POST /ton-adresse HTTP/1.1
Content-Type: application/json
User-Agent: Actero-Webhooks/2.0
X-Actero-Event: ticket.escalated
X-Actero-Timestamp: 1760090400
X-Actero-Signature: v1=4b5d7e8a9c0b1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e

{
  "event": "ticket.escalated",
  "id": "5f0c2b7e-…",
  "timestamp": "2026-10-10T10:00:00.000Z",
  "client_id": "01HX…",
  "data": {
    "conversation_id": "9b1d…",
    "canal": "widget",
    "classification": "complaint",
    "raison": "aggressive",
    "sujet": "Colis",
    "extrait": "Bonjour, ma commande n'est pas arrivée…",
    "client": { "email": "client@exemple.fr", "nom": "Marie" }
  }
}

Champ de `data`	Présent pour	Contenu
`conversation_id`	les trois	Identifiant de la conversation dans Actero (peut être `null`).
`canal`	les trois	`widget`, `email`, `zendesk`, `gorgias`, `portail` ou `api`.
`classification`	les trois	Intention lue par l’agent (ex. `order_tracking`).
`raison`	`ticket.escalated`	Pourquoi l’agent passe la main.
`confiance`	`ticket.resolved`	Confiance de l’agent, de 0 à 1.
`reponse`	`ticket.resolved`	La réponse envoyée (1 000 caractères au plus).
`sujet`, `extrait`	les trois	Objet (200 caractères) et début du message du client (500 caractères).
`client`	les trois	`{ email, nom }` du client quand ils sont connus, sinon `null`.

Le contenu de data peut s’enrichir : code défensivement. conversation_id vaut null quand l’agent passe la main dès le tout premier message, avant que la conversation soit enregistrée.

Changé le 10 octobre 2026 : la charge de ticket.escalated utilisait customer_email, customer_name, subject et message_preview. Elle utilise maintenant les clés ci-dessus. Mets à jour un outil branché sur l’ancienne charge.

Vérifier la signature

X-Actero-Signature contient v1=<hex> où <hex> est le HMAC-SHA256 de la chaîne <timestamp>.<raw_body> calculée avec ton secret.

import crypto from 'crypto'

function verifyActeroSignature(req, secret) {
  const sig = req.headers['x-actero-signature']?.replace(/^v1=/, '')
  const ts = req.headers['x-actero-timestamp']
  if (!sig || !ts) return false

  // Anti-rejeu : refuser les requêtes vieilles de plus de 5 minutes.
  const age = Math.abs(Date.now() / 1000 - Number(ts))
  if (age > 300) return false

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${ts}.${req.rawBody}`)
    .digest('hex')

  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
}

import hmac, hashlib, time

def verify_actero_signature(headers, raw_body, secret):
    sig = headers.get("x-actero-signature", "").removeprefix("v1=")
    ts = headers.get("x-actero-timestamp", "")
    if not sig or not ts:
        return False
    if abs(time.time() - int(ts)) > 300:
        return False  # anti-rejeu

    expected = hmac.new(
        secret.encode(),
        f"{ts}.{raw_body.decode()}".encode(),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(sig, expected)

# Reproduire une signature en local pour debug
echo -n "1745318400.$(cat body.json)" \
  | openssl dgst -sha256 -hmac "$WHSEC" \
  | awk '{print "v1="$2}'

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

Réponse de ton serveur	Ce que fait Actero
`2xx`	Envoi réussi, le compteur d’échecs revient à 0.
`3xx`	Redirection jamais suivie : compté comme un échec.
`4xx` ou `5xx`	Échec, sans nouvel essai automatique.
Pas de réponse en 5 s	Échec.

Il n’y a pas de nouvel essai automatique. Après 20 échecs de suite, le webhook est coupé ; le réactiver depuis la page remet le compteur à 0. Un test raté ne compte pas. Actero vérifie à chaque envoi que l’adresse est toujours en https sur un hôte public, et que la formule de la boutique inclut toujours les webhooks.

Idempotence

Chaque envoi porte un id unique. En cas de souci réseau, ton serveur peut recevoir deux fois le même envoi : déduplique par id.

Référence

Endpoints

Configuration

Événements disponibles

Format de la requête

Vérifier la signature

Réponse attendue

Idempotence

​Configuration

​Événements disponibles

​Format de la requête

​Vérifier la signature

​Réponse attendue

​Idempotence

Configuration

Événements disponibles

Format de la requête

Vérifier la signature

Réponse attendue

Idempotence