Être prévenu quand un document change
FakturBi appelle votre serveur dès qu'une facture est finalisée, qu'un avoir est créé ou qu'une vente de caisse est enregistrée. Vous n'avez pas à interroger l'API en boucle.
1. Déclarez une adresse
Dans FakturBi, menu Développeurs › Notifications, ajoutez l'adresse HTTPS de votre serveur et cochez les événements voulus. La clé secrète whsec_… s'affiche une seule fois : conservez-la.
2. Ce que vous recevez
Une requête POST en JSON. L'enveloppe est la même pour tous les événements ; livemode vaut false pour un document d'essai.
{
"id": "evt_8Kq2mXa7Hc",
"type": "einvoicing.invoice.finalized",
"created": "2026-11-16T10:48:12Z",
"livemode": false,
"api_version": "v1",
"request_id": "req_7Hc2kQ9mXa",
"data": { "object": { "invoiceNumber": "TEST-2026-42A608117D", "status": "FINALIZED", "totalAmount": 29500.00, "currency": "XOF" } }
}
3. Vérifiez la signature
Chaque requête porte l'en-tête FakturBi-Signature: t=…,v1=…. Recalculez v1 avec votre clé secrète et refusez tout message vieux de plus de 5 minutes.
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifier(corps: string, enTete: string, secret: string): boolean {
const { t, v1 } = Object.fromEntries(enTete.split(",").map((p) => p.split("=")));
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const attendu = createHmac("sha256", secret).update(`${t}.${corps}`).digest("hex");
return attendu.length === v1.length && timingSafeEqual(Buffer.from(attendu), Buffer.from(v1));
}
Signez sur le corps brut. Calculez la signature sur le texte reçu, avant toute lecture du JSON.
4. Répondez vite, traitez ensuite
Répondez 2xx en moins de 10 secondes. Un même événement peut arriver deux fois et l'ordre n'est pas garanti : utilisez id pour ignorer les doublons.
Sans réponse 2xx, FakturBi renvoie l'événement à intervalles croissants pendant 72 heures : 1 min, 5 min, 30 min, 2 h, 6 h, puis toutes les 12 h. Passé ce délai, l'adresse est mise en pause et vous êtes prévenu.
5. Testez et rattrapez
Le bouton « Envoyer un essai » de l'écran Notifications envoie un événement factice à votre adresse. Chaque envoi reste visible 30 jours, avec le code de réponse de votre serveur, et peut être renvoyé d'un clic.
Si votre serveur a été arrêté plus longtemps, relisez ce qui a été manqué avec GET /events.