Aller au contenu

Guides

Bonnes pratiques

Secrets

  • Conservez secrets de client et de webhook dans un coffre de secrets, jamais dans le code ni les journaux.
  • Planifiez une rotation régulière en utilisant la période de recouvrement.
  • Un client par système intégré : vous pourrez révoquer l’un sans interrompre les autres.

Scopes

Accordez le minimum. Un outil de reporting n’a besoin que de progress:read.

Fiabilité

  • Mettez en cache le jeton jusqu’à son expiration, puis redemandez-en un.
  • Envoyez une Idempotency-Key stable par opération métier (par exemple l’identifiant de l’événement RH) et réessayez avec la même clé après une erreur réseau.
  • Sur 429 ou 5xx, attendez Retry-After ou appliquez un délai exponentiel avec gigue.
  • Parcourez les listes avec le curseur ; n’assemblez pas vous-même de pagination par numéro.

Webhooks

  • Répondez 2xx en moins de 10 secondes, puis traitez en différé.
  • Vérifiez la signature et l’horodatage avant tout traitement.
  • Dédupliquez sur webhook-id : une livraison peut être répétée.
  • Relisez l’API pour le détail : le message ne contient que des identifiants et les faits essentiels.