Les webhooks permettent de recevoir des notifications sans dépendre uniquement de consultations périodiques. Avec une API Verifactu, concevez-les comme un élément du suivi : recevoir un événement, identifier son document et déterminer la mise à jour appropriée. Le récepteur doit aussi gérer les événements répétés ou inattendus.
Partez des types réellement disponibles
Notre référence API propose des opérations pour consulter les types de webhook, configurer une URL et examiner les webhooks enregistrés. Consultez-les avant de concevoir le récepteur. Confirmez le format exact des notifications et leur authentification avec l’équipe ; n’inventez pas de signature, d’en-tête ou de garantie de livraison absents du contrat.
Reliez chaque notification à une opération
Conservez les identifiants renvoyés lors des envois pour associer le résultat au document local. La documentation prévoit des consultations d’envois identifiés par queueId. Gardez cette référence technique séparée du numéro commercial de facture afin d’éviter les liens ambigus, notamment lorsque vous gérez plusieurs entreprises.
Rendez les répétitions sans effet indésirable
Concevez les changements de statut pour qu’un événement traité deux fois ne duplique aucune action. Vérifiez le statut enregistré avant de déclencher des messages ou des tâches ultérieures. Ne supposez pas que les notifications arrivent dans l’ordre attendu par l’interface ; en cas de doute, utilisez les consultations disponibles et évitez de remplacer un résultat connu par un ancien.
- Validez l’authentification et la structure reçue.
- Vérifiez l’entreprise et le document concernés.
- Enregistrez une référence utile à l’analyse des incidents.
- Testez doublons, retards et erreurs temporaires du récepteur.
Conservez une procédure de rapprochement
Un webhook ne dispense pas d’examiner les opérations dont le statut local est devenu obsolète. Définissez un rapprochement respectant les limites du service et une file d’incidents pour l’équipe. Vous pourrez ainsi rétablir le suivi après une interruption sans multiplier les envois ni effectuer des modifications manuelles sans trace.