Webhooks

Les webhooks AuraPOS vous permettent d'être notifié en temps réel des événements qui se produisent dans votre commerce (nouveau ticket, modification client, etc.) sans avoir à interroger l'API en polling.

Disponibilité

Accessible depuis le backend web AuraPOS, donc :

• Inclus dans les éditions Group et Restaurant Group
• Optionnel à 24 €/mois pour les éditions Express / Boutique / Studio / Restaurant

Comment ça marche

1. Vous créez un webhook dans Paramètres → Webhooks (Owner uniquement)
2. Vous donnez une URL HTTPS publique où AuraPOS pourra envoyer les notifications
3. Vous sélectionnez les événements que vous voulez écouter (multi-sélection)
4. AuraPOS génère un secret HMAC unique pour ce webhook (affiché une seule fois, copiez-le)
5. À chaque événement, AuraPOS envoie un POST signé HMAC-SHA256 à votre URL
6. Vous traitez la notification côté serveur (votre Slack, votre ERP, etc.)

Les 7 événements disponibles

Format du payload

À chaque événement, AuraPOS envoie un POST JSON :

{
  "event": "ticket.created",
  "delivery_id": "uuid-de-cette-livraison",
  "created_at": "2026-05-17T14:32:08.123Z",
  "payload": {
    "numero": 1234,
    "numero_facture": "FAC-2026-0042",
    "date_heure": "2026-05-17T14:31:55Z",
    "client_global_id": "uuid-client-ou-null",
    "total_htva": 45.78,
    "total_tva": 9.61,
    "total_tvac": 55.39,
    "mode_paiement": "Bancontact",
    "mode_consommation": "SurPlace",
    "annule": false,
    "est_facture": true,
    "lignes": [
      {
        "nom": "Steak frites",
        "quantite": 1,
        "taux_tva": 12,
        "montant_tvac": 18.50
      }
    ]
  }
}

Headers HTTP envoyés

POST /votre-endpoint HTTP/1.1
Content-Type: application/json
User-Agent: AuraPOS-Webhooks/1.0
X-AuraPOS-Event: ticket.created
X-AuraPOS-Delivery: uuid-de-cette-livraison
X-AuraPOS-Signature: sha256=<hex hmac du body>

Vérification de la signature (sécurité)

⚠️ Toujours vérifier la signature HMAC pour s'assurer que la requête provient bien d'AuraPOS et n'a pas été forgée.

Node.js

import crypto from "node:crypto";

function verifySignature(req, secret) {
  const signature = req.headers["x-aurapos-signature"];
  if (!signature) return false;
  const [algo, hash] = signature.split("=");
  if (algo !== "sha256") return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(req.rawBody)  // body brut, pas le JSON parsé
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(hash, "hex"),
    Buffer.from(expected, "hex"),
  );
}

PHP

function verifySignature($rawBody, $signature, $secret) {
  $expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
  return hash_equals($expected, $signature);
}

Python

import hmac, hashlib

def verify_signature(raw_body, signature, secret):
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Fiabilité : retry exponentiel automatique

Si votre endpoint :

• Retourne un statut HTTP entre 200 et 299 → delivered (livraison réussie)
• Retourne un statut autre OU timeout après 10 s → failed, retry programmé

Backoff exponentiel : 1 min, 5 min, 30 min, 2 h, 12 h (max 5 tentatives).

Après 5 échecs : statut abandoned, visible dans l'historique pour debug. La livraison n'est plus retentée automatiquement.

Historique des livraisons

Dans la page d'édition d'un webhook, vous voyez les 50 dernières livraisons :

• Date + événement
• Statut : pending (en attente), delivered (réussi), failed (en retry), abandoned (5 échecs)
• Code HTTP retourné par votre endpoint
• Nombre de tentatives
• Premier 500 chars du body de réponse (utile pour debug)

Bouton "Envoyer test"

Avant de mettre en prod, testez votre intégration depuis l'UI. Le bouton Envoyer test (event ping) enqueue un événement spécial qui sera livré au prochain tick du worker (max 1 min).

Le payload contient { message: "Test webhook depuis AuraPOS", sent_at: "..." }. Idéal pour valider que votre handler reçoit, parse, et vérifie correctement la signature.

Latence

Le worker tick tourne toutes les minutes (cron systemd côté VPS). La latence max entre l'événement et la notification webhook est donc d'environ 1 minute.

Pour les tickets desktop : ajoutez ~15 min (push BackendSync) avant le déclenchement de l'événement, soit 16 min max entre une vente en caisse et la réception du webhook.

Cas d'usage typiques

Notification équipe

• Webhook → Slack incoming webhook → message "💰 Ticket #1234 — 145 €" dans le canal #ventes
• Filtre côté votre relay : seulement si total > 100 €

Sync CRM

• Webhook client.created → API Mailchimp / Brevo / Sendinblue → ajout dans liste "Nouveaux clients"
• Déclenchement workflow welcome email

Workflow Make / Zapier

• Webhook → Make.com / Zapier → enchaîne 5 actions (Google Sheets log + Slack + email + Trello)

Push catalogue e-commerce

• Webhook produit.updated → script qui pull /api/v1/produits/{id} → POST vers votre plateforme e-commerce
• Garantit que catalogue web reste à jour avec la caisse

Dashboard BI temps réel

• Webhook → endpoint Webflow / Grafana / Metabase → mise à jour graphique en direct

Gestion d'un endpoint qui tombe

Si votre endpoint est down pendant qq heures :

• Les premières tentatives échouent → retry à 1min, 5min, 30min, 2h
• Si vous remontez avant la 5ᵉ tentative, la livraison passe en delivered
• Si toujours down après 12h, statut abandoned → vous devez manuellement re-pull les événements perdus via l'API REST /api/v1/tickets?debut=...

Pour les intégrations critiques (compta), il est conseillé d'avoir aussi un job hebdo qui re-pull les tickets via l'API pour combler les éventuels abandoned.

Régénération du secret

Si le secret HMAC fuite, depuis l'édition du webhook : Régénérer le secret (invalide l'ancien). Toute requête signée avec l'ancien secret sera rejetée par votre handler.

Mettez à jour le secret côté consumer immédiatement après la régénération.

Suppression

Bouton Supprimer dans la zone de danger. La suppression est définitive et arrête immédiatement les livraisons.