Configuration des webhooks

Recevoir des notifications en temps réel sur les événements Maestor.

Les webhooks Maestor vous notifient en temps réel des événements importants — création SAV, signature, clôture, etc. Signature HMAC-SHA256 pour vérifier l’authenticité.

Configurer un webhook

1. Connectez-vous à app.maestor.eu
2. Paramètres → API → Webhooks
3. Cliquez sur Ajouter un webhook
4. Renseignez :
   • URL endpoint (HTTPS uniquement, sauf en dev local)
   • Événements à recevoir (cochez parmi les 13 disponibles)
   • Description libre (pour vous y retrouver)
5. Copiez le secret de signature (affiché une seule fois)

Format du payload

POST /votre-endpoint HTTP/1.1
Content-Type: application/json
X-Webhook-Signature: sha256=abc123...
X-Webhook-Timestamp: 1706800000
X-Webhook-Event: sav.created

{
  "event": "sav.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": 123,
    "reference": "SAV-2024-00123",
    ...
  }
}

Vérifier la signature

Le header X-Webhook-Signature contient une signature HMAC-SHA256 du corps de la requête, signé avec votre secret.

Exemple en PHP :

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];
$expected = 'sha256=' . hash_hmac('sha256', $payload, $webhook_secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

$event = json_decode($payload, true);
// Traiter l'événement

Exemple en Node.js :

import crypto from 'node:crypto';

function verifySignature(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Retry policy

Si votre endpoint retourne un code >= 300 ou met plus de 5 secondes à répondre, Maestor retente avec une backoff exponentielle :

Après la 6e tentative, le webhook est marqué comme failed et visible dans Paramètres → API → Webhooks → Historique.

Réponse rapide : Retournez 200 OK immédiatement, puis traitez le payload en asynchrone (queue). Ne bloquez pas la requête sur des opérations longues.

Étapes suivantes

• Liste des 13 événements disponibles
• Vérification de signature avancée