Envoyer des événements à vos systèmes avec les webhooks

Prévenez votre serveur quand des tickets, messages, clients ou évaluations changent, vérifiez la signature et suivez les envois et les nouveaux essais.

Web
Sur cette page
  1. Ajouter un webhook
  2. Événements
  3. Vérifier la signature
  4. Réponses, nouveaux essais et journal

Un webhook envoie un message à votre serveur chaque fois qu’il se passe quelque chose dans l’espace, pour qu’un autre système réagisse : mettre à jour un CRM, publier dans un canal, lancer un processus. Les webhooks sont gérés par les administrateurs.

Ajouter un webhook

  1. Allez dans Paramètres, puis Webhooks, et sélectionnez Ajouter un webhook.
  2. Saisissez un Nom et l’URL de votre récepteur. Elle doit utiliser https ; les adresses privées, locales et de métadonnées cloud sont refusées.
  3. Cochez les Événements voulus.
  4. Enregistrez, puis copiez le Secret de signature : il ne sera plus affiché.

Un espace peut avoir jusqu’à 20 webhooks. Sélectionnez Envoyer un test pour livrer tout de suite un événement ping et voir la réponse de votre serveur.

Événements

Événement Envoyé quand
ticket.created Un ticket est créé, quel que soit le canal
ticket.updated Les champs d’un ticket changent, avec la liste des changements
ticket.solved Un ticket passe à résolu
message.created Un message est ajouté à un ticket
customer.created Un nouveau client est créé
csat.received Un client répond à l’enquête de satisfaction

Chaque envoi est un POST avec un corps JSON :

{
  "id": "6f1c2a52-8d0e-4a7b-9f3e-2b1d7c4e9a10",
  "event": "ticket.solved",
  "created_at": "2026-11-07T09:30:00Z",
  "workspace_id": "0b6e…",
  "data": {
    "ticket": {
      "number": 42,
      "subject": "Order not delivered",
      "status": "solved",
      "priority": "normal",
      "requester": { "name": "Ana Haddad", "email": "ana@example.com" }
    }
  }
}

Les en-têtes X-Aoun-Event (l’événement) et X-Aoun-Delivery (cet envoi) l’accompagnent. L’id du corps reste le même si un envoi est renvoyé : servez-vous-en pour ignorer un événement déjà traité.

Vérifier la signature

Chaque envoi porte X-Aoun-Signature: t=<heure>,v1=<signature>. La signature est le HMAC-SHA256, en hexadécimal, de l’heure, d’un point et du corps brut, avec votre secret de signature comme clé. Vérifiez-la sur le corps brut, avant de lire le JSON, comparez en temps constant et refusez les heures de plus de 5 minutes.

Node.js (Express):

import crypto from 'node:crypto';
import express from 'express';

const app = express();

app.post('/aoun-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = Object.fromEntries(
    (req.get('X-Aoun-Signature') || '').split(',').map((p) => p.split('=')),
  );
  const expected = crypto
    .createHmac('sha256', process.env.AOUN_WEBHOOK_SECRET)
    .update(`${sig.t}.`)
    .update(req.body)
    .digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(sig.t)) < 300;
  const valid = fresh && typeof sig.v1 === 'string' && sig.v1.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(sig.v1), Buffer.from(expected));
  if (!valid) return res.status(401).end();

  const event = JSON.parse(req.body);
  // event.event, event.data …
  res.status(204).end();
});

PHP:

$body = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_AOUN_SIGNATURE'] ?? ''), $sig);
$t = $sig['t'] ?? '';
$expected = hash_hmac('sha256', $t . '.' . $body, getenv('AOUN_WEBHOOK_SECRET'));

if (abs(time() - (int) $t) > 300 || !hash_equals($expected, $sig['v1'] ?? '')) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true);
// $event['event'], $event['data'] …
http_response_code(204);

Python (Flask):

import hashlib, hmac, os, time
from flask import Flask, abort, request

app = Flask(__name__)

@app.post("/aoun-webhook")
def aoun_webhook():
    body = request.get_data()
    header = request.headers.get("X-Aoun-Signature", "")
    sig = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t = sig.get("t", "0")
    expected = hmac.new(
        os.environ["AOUN_WEBHOOK_SECRET"].encode(),
        t.encode() + b"." + body,
        hashlib.sha256,
    ).hexdigest()
    if not t.isdigit() or abs(time.time() - int(t)) > 300 or not hmac.compare_digest(expected, sig.get("v1", "")):
        abort(401)
    event = request.get_json()
    # event["event"], event["data"] …
    return "", 204

Réponses, nouveaux essais et journal

Répondez avec un statut 2xx en moins de 10 secondes. Sinon, Aoun réessaie après 1, 5 et 30 minutes, puis 2, 6 et 12 heures, avant de marquer l’envoi Échec. Après 20 envois échoués d’affilée, le webhook est désactivé ; corrigez le récepteur, puis réactivez-le.

Sélectionnez les Envois d’un webhook pour voir les 30 derniers jours : état (Livré, En attente de nouvel essai, Échec), nombre d’essais, réponse de votre serveur et corps envoyé. Renvoyer remet n’importe quel envoi dans la file.

Nouveau secret remplace le secret de signature immédiatement : mettez votre récepteur à jour avec le nouveau.