Concevoir une API B2B fiable : authentification, webhooks et gestion des erreurs

Définir le contrat métier avant les endpoints

Une API expose des opérations et des données, mais leur sens doit être partagé. Décrivez les objets, les identifiants, les unités, les dates et les transitions autorisées. Une commande créée, confirmée ou annulée ne représente pas le même engagement. Le partenaire doit savoir quelles informations sont obligatoires et quelles modifications restent possibles selon l’état.

Le contrat de données précise aussi les valeurs absentes et les erreurs de validation. Un montant sans devise, une date sans convention ou un identifiant recyclé créent des ambiguïtés difficiles à corriger après synchronisation. Ajoutez des exemples valides et invalides. Nommez un responsable pour les questions de sens et une procédure d’annonce des changements, afin que la documentation reste un engagement utilisable.

Séparer authentification et autorisation

L’authentification identifie un client technique ou une personne. L’autorisation détermine les opérations et objets auxquels cette identité peut accéder. Une clé valide ne doit pas permettre de lire le dossier d’une autre organisation en changeant simplement son identifiant. L’OWASP identifie précisément le défaut de contrôle au niveau des objets parmi les risques majeurs des API.

Appliquez les permissions à chaque lecture et écriture, y compris aux exports et aux opérations groupées. Limitez la portée des secrets, prévoyez leur rotation et leur révocation, puis évitez leur présence dans les URL ou les journaux. Si une délégation OAuth est pertinente, documentez ses scopes et son cycle de vie. Le choix du mécanisme doit correspondre au parcours de délégation attendu, pas seulement à une préférence technique.

Pour approfondir : OWASP — autorisation au niveau des objets

Rendre les opérations rejouables sans répéter leurs effets

Après un délai d’attente, le client peut ignorer si une création a abouti. Relancer avec une nouvelle identité risque de créer un doublon. L’idempotence consiste à définir le comportement d’une même opération répétée. Stripe documente l’usage de clés pour certaines requêtes de son API ; les règles de conservation et de comparaison dépendent du service concerné.

Dans votre contrat, précisez la portée de la clé, sa durée utile et le traitement d’une même clé avec des paramètres différents. Enregistrez l’état de l’opération de manière cohérente avec son effet métier. Deux requêtes concurrentes ne doivent pas contourner le contrôle. Pour une modification d’objet, une version attendue permet aussi de détecter qu’un autre traitement l’a changé depuis sa lecture, plutôt que d’écraser silencieusement une information récente.

Pour approfondir : Stripe — requêtes idempotentes

Recevoir des webhooks comme des notifications à vérifier

Un webhook informe un système qu’un événement s’est produit ailleurs. Le récepteur doit vérifier son origine et suivre le mécanisme de signature prévu par l’émetteur. La documentation Stripe précise notamment l’importance du corps brut pour cette vérification et décrit les livraisons répétées possibles. Ces détails doivent être lus pour le fournisseur réellement intégré.

Enregistrez la réception de manière durable avant d’acquitter un événement accepté, puis séparez le traitement long de la réponse HTTP. Identifiez les événements déjà traités. Ne supposez pas un ordre garanti si le contrat ne le promet pas : un événement de mise à jour peut être reçu avant un autre attendu. Lorsque nécessaire, relisez l’état courant via l’API autorisée pour décider de la transition métier.

Pour approfondir : Stripe — réception et vérification des webhooks

Définir les erreurs, délais et limites de reprise

Distinguez une entrée invalide, un accès refusé, une ressource absente, un conflit d’état et une indisponibilité temporaire. Le client doit savoir quand corriger la demande et quand une reprise peut être tentée. Une erreur métier ne doit pas être relancée indéfiniment comme une panne transitoire.

La limitation de débit protège les ressources, mais son comportement doit être documenté. Les reprises peuvent utiliser une attente progressive et une variation aléatoire pour éviter que tous les clients recommencent ensemble. Fixez un nombre maximal d’essais et un état final visible. Un timeout ne signifie pas nécessairement que rien n’a été exécuté : avant de rejouer une écriture, recherchez son état avec l’identité d’opération connue.

Exploiter les versions et rapprocher les systèmes

Préparez une évolution de schéma compatible avec les usages connus. L’ajout d’un champ peut sembler anodin, mais un client strict peut rejeter une valeur nouvelle ou une enum étendue. Testez les consommateurs importants et annoncez les changements incompatibles avec une période de transition adaptée au contrat.

La supervision doit suivre délais, erreurs, files en attente et divergences métier. Prévoyez un rapprochement périodique : comparer les commandes attendues et reçues peut révéler un événement jamais livré ou un traitement resté bloqué. Un tableau de bord HTTP ne voit pas toujours ces écarts. Conservez les identifiants de corrélation et une procédure de reprise que le support peut utiliser sans rejouer aveuglément toutes les données.