Webhooks : Configuration, Sécurité et Autorisations

Les webhooks permettent une communication "Push" : FIAB Gestion informe votre serveur d'un événement dès qu'il se produit.

🛑 Étape 1 : L'autorisation administrative

Même avec un plan Pro ou Custom, l'accès aux webhooks est désactivé par défaut par mesure de sécurité.

• Le message "Accès Restreint" : Si vous voyez ce message dans Mon Profil > Webhooks, cela signifie que votre compte n'est pas encore autorisé à émettre des données vers l'extérieur.

• Activation : Vous devez contacter l'administrateur FIAB pour demander l'activation de l'autorisation Webhook pour votre entreprise. Une fois validée, l'interface de configuration deviendra interactive.

🛡️ Étape 2 : Sécurisation par Signature HMAC (SHA256)

FIAB signe chaque requête pour que vous puissiez vérifier qu'elle n'a pas été interceptée ou falsifiée.

• Header : X-FIAB-Signature (ex: sha256=a1b2c3d4...)

• Vérification : Vous devez calculer le hash HMAC-SHA256 du corps JSON reçu en utilisant votre Secret Webhook (disponible dans votre profil) comme clé.

Exemple de vérification (Node.js) :

javascript

const signature = req.headers['x-fiab-signature'];

const hmac = crypto.createHmac('sha256', YOUR_WEBHOOK_SECRET);

const digest = 'sha256=' + hmac.update(JSON.stringify(req.body)).digest('hex');

if (signature === digest) {

// La requête est authentique

}

📦 Étape 3 : Format des données (Payload JSON)

FIAB envoie un objet riche qui s'adapte selon la cible de la notification.

Exemple de payload (Notification automatique au client) :

json

{

"entrepriseId": "clx...",

"entreprise": "Logistique Express",

"numeroSuivi": "CMD-2024-001",

"emailClient": "[email protected]",

"telephoneClient": "+22901234567",

"statut": "livre",

"modeTransport": "Terrestre",

"dateLivraison": "2024-04-21T10:30:00Z",

"triggerType": "AUTO",

"target": "client",

"timestamp": "2024-04-21T10:31:00Z"

}

Note : Si la cible (target) est le destinataire (recipient), le champ telephoneClient contiendra le numéro du receveur pour vos automatisations de type SMS.

Utiliser l'API de Recherche pour le Suivi Externe

L'API de recherche est une API de type "Pull" qui permet d'intégrer le suivi FIAB directement dans votre propre application, site web ou Bot WhatsApp (White-Label).

🔑 Authentification par Clé Partenaire

L'accès à cet endpoint nécessite un header spécifique x-api-key. Cette clé est strictement confidentielle et ne doit jamais être exposée côté client (frontend).

📡 Requête de recherche

• Endpoint : POST /api/external/livraison

• Header : x-api-key: VOTRE_CLE_PARTENAIRE

Body (JSON) :

json

{

"numeroSuivi": "CMD-2024-001"

}

📥 Structure de la réponse (Réussite 200 OK)

La réponse contient non seulement l'état actuel, mais aussi la "Timeline" complète des événements.

json

{

"livraison": {

"numero_suivi": "CMD-2024-001",

"status": "en_transit",

"date_debut": "2024-04-20T08:00:00Z",

"informations": "Colis fragile",

"mode_transport": "Moto"

},

"entreprise": {

"nom_entreprise": "Logistique Express",

"telephone": "+22901010101"

},

"updates": [

{

"nouveau_statut": "en_preparation",

"commentaire": "Colis réceptionné au centre",

"date": "2024-04-20T08:15:00Z"

},

{

"nouveau_statut": "en_transit",

"commentaire": "Livreur en route vers la destination",

"date": "2024-04-21T09:00:00Z"

}

]

}

Dépannage et Bonnes Pratiques Techniques

🔄 Système de retry et Résilience

FIAB Gestion est conçu pour la haute disponibilité. Si votre serveur ne répond pas par un 200 OK :

1. Tentatives : Le système effectue jusqu'à 3 tentatives automatiques.

2. Délai : Un délai exponentiel est appliqué entre chaque essai (1s, 2s, 3s).

3. Timeout : Votre serveur doit répondre en moins de 120 secondes.

📉 Gestion des Quotas

Chaque notification webhook réussie incrémente votre compteur Webhooks utilisés.

• Vous pouvez suivre votre consommation en temps réel sur le Dashboard Finance.

• En cas d'échec critique (après 3 tentatives), vous recevrez une notification interne dans votre dashboard FIAB pour vous alerter du problème sur votre serveur.

💡 Recommandation de sécurité

Nous vous conseillons de régénérer votre secret webhook tous les 90 jours ou immédiatement si un membre de votre équipe technique quitte l'entreprise. Cette opération se fait dans l'onglet Profil > Webhooks et nécessite la confirmation de votre mot de passe administrateur.