Bonnes pratiques d’intégration

Sécurité

• Rangez les jetons et les secrets de webhook dans un gestionnaire de secrets, jamais dans le code. Un jeton commité se reconnaît à son préfixe nf_ : révoquez-le aussitôt.
• Un jeton par intégration, avec les seuls scopes dont elle a besoin. Révoquer l’un ne coupe pas les autres.
• Vérifiez la signature de chaque webhook, sur le corps brut, en temps constant.

Écritures sûres

• Envoyez une Idempotency-Key sur chaque création, et la même clé quand vous réessayez.
• Réessayez les 5xx et les 429 avec un délai croissant ; ne réessayez jamais un 401, un 403 ou un 422 sans rien changer.

Économie de débit

• Abonnez un webhook plutôt que de sonder ; si vous sondez, espacez les appels et respectez Retry-After.
• Renvoyez l’ETag reçu dans If-None-Match : une réponse 304 ne coûte rien.
• Lisez le résumé des anomalies avant de paginer leurs occurrences.

Lire les chiffres honnêtement

• null veut dire « non mesuré », jamais zéro. Une moyenne voyage avec son dénominateur : lisez-le.
• Un crawl tronqué ou bloqué (comparable: false) ne se compare pas.
• Appuyez-vous sur les code, jamais sur les title, qui se traduisent.