Configurer les webhooks client
Enregistrez un récepteur HTTPS pour les événements pris en charge, protégez son secret de signature et consultez l’historique des envois pour diagnostiquer les échecs.
- Préparer le récepteurUtilisez un point de terminaison HTTPS public prêt à recevoir du JSON.
- S’abonner aux événementsIndiquez un nom et une URL pour le point de terminaison, puis choisissez les types d’événement.
- Protéger la signatureStockez le secret affiché une seule fois et vérifiez les requêtes reçues.
- Vérifier les envoisConsultez leur état et les informations de réponse pour résoudre les problèmes.
- Maintenir le point de terminaisonRenouvelez les secrets ou révoquez les destinations devenues inutiles.
Événements client disponibles
Le formulaire client propose les événements job finished, invoice issued et quota threshold. Choisissez uniquement ceux que votre récepteur sait traiter. Les points de terminaison appartiennent à votre contexte personnel ou à l’organisation sélectionnée. Les propriétaires et administrateurs de l’organisation peuvent les gérer ; les membres peuvent les consulter sans les modifier. Un webhook envoie des notifications ; il ne modifie pas lui-même une commande ou une facture.
- Ouvrez Webhooks dans le contexte de l’organisation voulu.
- Choisissez au moins un événement pris en charge par votre récepteur.
- Utilisez des points de terminaison distincts pour les environnements différents.
Enregistrer une destination publique
Créez un point de terminaison avec un nom de 2 à 120 caractères, une URL valide et un ou plusieurs événements proposés. Un hôte public et HTTPS sont obligatoires. Les destinations locales, internes ou sur une adresse IP privée sont refusées ; une URL de développement locale ne fonctionnera donc pas. Envoyez le formulaire lorsque le récepteur peut accepter du JSON et renvoyer une réponse HTTP positive.
- Déployez le récepteur à une adresse HTTPS publique et stable.
- Indiquez son URL, un nom explicite et les événements voulus.
- Envoyez le formulaire une fois et corrigez les éventuelles erreurs de validation.
Vérifier les messages signés
La création affiche le secret de signature une seule fois. Les requêtes contiennent les en-têtes event, delivery, timestamp et signature HMAC, ainsi qu’un corps JSON avec l’identifiant et le type de l’événement, sa date de création et ses données. Vérifiez la signature sur l’horodatage et le corps brut exact, imposez une fenêtre temporelle raisonnable et traitez les identifiants en double de façon idempotente. Ne placez pas le secret dans les journaux ou messages d’assistance.
- Stockez le secret dans la configuration protégée du récepteur.
- Vérifiez la signature à partir du corps de requête non modifié.
- Enregistrez les identifiants des événements pour éviter de répéter des opérations métier.
Consulter l’historique des envois
La page affiche les 50 envois les plus récents, tous points de terminaison confondus. Les réponses HTTP positives sont marquées comme réussies. Les erreurs serveur et les limitations de débit peuvent donner lieu à une nouvelle tentative ; les autres réponses négatives peuvent échouer immédiatement et les tentatives s’arrêtent à la limite prévue. L’historique indique le statut de réponse et un extrait limité du corps ou l’erreur. Un événement peut être absent s’il ne s’est pas produit ou si le point de terminaison n’y était pas abonné.
- Examinez l’événement, le nombre de tentatives, l’état et la dernière erreur.
- Corrigez la disponibilité du récepteur, sa réponse ou la limitation de débit.
- Vérifiez qu’un envoi ultérieur aboutit.
Renouveler le secret de signature
Le renouvellement remplace le secret du point de terminaison et le réactive. Les récepteurs qui n’utilisent que l’ancienne valeur rejetteront les nouvelles requêtes. Préparez la mise à jour de leur configuration, renouvelez le secret sur la ligne du point de terminaison concerné, récupérez la nouvelle valeur et déployez-la rapidement. En cas de compromission, renouvelez-la sans délai et recherchez toute activité inhabituelle dans l’historique des envois.
- Identifiez les instances du récepteur et préparez un déploiement sécurisé.
- Renouvelez le secret du point de terminaison et stockez la nouvelle valeur affichée une seule fois.
- Vérifiez qu’un prochain envoi attendu aboutit.
Remplacer ou révoquer un point de terminaison
Les commandes client permettent de créer, renouveler et révoquer un point de terminaison ; elles ne permettent pas de modifier son URL ou les événements choisis. Pour changer l’un de ces éléments, créez un remplacement, vérifiez qu’il reçoit les bons événements, puis révoquez l’ancien. La révocation arrête les futurs envois et marque le point de terminaison comme inactif. Procédez ainsi pour retirer une destination ou après la compromission d’un secret, puis vérifiez la liste.
- Créez un remplacement avec l’URL ou les événements corrigés.
- Confirmez que le nouveau point de terminaison reçoit correctement un événement.
- Révoquez l’ancien et vérifiez qu’il est inactif.
Questions fréquentes
Quels événements sont proposés ?
job finished, invoice issued et quota threshold.
Puis-je utiliser HTTP sans chiffrement ?
Non. Une URL HTTPS publique est obligatoire.
Puis-je afficher de nouveau le secret ?
Non. Renouvelez le secret du point de terminaison pour en obtenir un nouveau.
Pourquoi un envoi est-il en attente ?
Une erreur serveur temporaire ou une limitation de débit peut entraîner une nouvelle tentative.
Pourquoi un envoi a-t-il échoué ?
Consultez la réponse et l’historique des tentatives pour en connaître la cause.
Puis-je modifier le point de terminaison ?
Non. Créez un remplacement, vérifiez-le, puis révoquez l’ancien.