Un webhook envoie un message à une adresse qui vous appartient chaque fois que quelque chose se passe dans votre espace de travail, par exemple quand une commande est payée ou qu'un abonnement est résilié. Utilisez-le pour garder un autre système synchronisé, comme un outil tel que Zapier, votre comptabilité ou votre propre serveur.
Ouvrir les paramètres des webhooks
Avant de commencer
La page se trouve sous Paiements > Paramètres > Webhooks, dans le groupe Développeurs. La consulter demande Voir les paiements. Ajouter, modifier, tester et supprimer des endpoints demande Mettre à jour les commandes / clients.
Ajouter un endpoint
Cliquez sur le bouton d'ajout pour ouvrir Ajouter un endpoint de webhook :
- Sous Point de terminaison, donnez-lui un Nom facultatif et saisissez l'URL du point de terminaison. L'adresse doit être accessible depuis internet. Les adresses d'un réseau privé sont refusées.
- Sous Événements, choisissez ce que l'endpoint doit recevoir. Rechercher des événements filtre la liste, la case d'un groupe sélectionne tout le groupe, et Tout sélectionner ou Tout effacer modifie tout d'un coup. Au moins un événement est nécessaire.
- Cliquez sur Créer.
Les événements sont regroupés par thème :
- Paiements : Commande payée, Paiement en cours, Paiement échoué, Facture payée, Remboursement créé.
- Abonnements : Abonnement créé, Abonnement renouvelé, Abonnement annulé, Échec du paiement de l'abonnement.
- Membres : inscriptions, connexions, tags ajoutés ou retirés, champs de membre modifiés et nouveaux contacts.
- Cours et événements, Communauté et Données et boîte de réception : cours et leçons terminés, inscriptions et présences aux événements, publications, niveaux, badges, messages de la boîte de réception et tickets.
- Affilié : nouvelles commissions et versements payés, voir l'aide sur l'affiliation.
Le secret de signature
Juste après la création de l'endpoint, l'espace de travail affiche son secret de signature une seule fois : Copiez votre secret de signature maintenant. Conservez-le de votre côté, puis cliquez sur Terminé. Il ne s'affiche plus.
Chaque livraison est envoyée en JSON avec l'en-tête X-Maio-Signature. Il
contient un HMAC-SHA256 du corps brut de la requête, calculé avec votre secret,
sous forme de chaîne hexadécimale en minuscules. Calculez la même valeur de
votre côté et comparez-la : vous savez ainsi que le message vient de votre
espace de travail. Les en-têtes X-Maio-Event et X-Maio-Delivery indiquent
l'événement et la livraison.
Pour remplacer le secret, ouvrez l'endpoint et cliquez sur Renouveler le secret. L'ancien secret cesse de fonctionner immédiatement, mettez donc votre endpoint à jour tout de suite.
Tester
Ouvrez l'endpoint et cliquez sur Envoyer un test. Le bouton devient Test en file d'attente, et un événement de test arrive sur votre endpoint en quelques instants. Il apparaît dans le journal de livraison comme toute autre livraison.
Le journal de livraison
L'onglet Journal de livraison liste chaque livraison avec son Événement, son Point de terminaison, son Statut, le statut HTTP renvoyé par votre endpoint, les Tentatives et Quand. Filtrez-le par Livré, Échoué ou En attente. La section Livraisons d'un endpoint affiche ses 20 livraisons les plus récentes, avec l'erreur de chaque livraison échouée.
Une livraison compte comme livrée quand votre endpoint répond avec un statut 2xx en moins de 15 secondes. Sinon, elle est retentée après 30 secondes, 5 minutes, 30 minutes, 2 heures et 6 heures. Renvoyer envoie une livraison à nouveau avec le même contenu.
Après 20 tentatives échouées d'affilée pour un événement, cet événement est désactivé pour l'endpoint. Si l'endpoint répond 410 Gone, l'événement est désactivé aussitôt. Corrigez l'endpoint, puis remettez-le sur Actif.
Désactiver et supprimer
Dans l'endpoint, l'interrupteur bascule entre Actif et Désactivé. Un endpoint désactivé ne reçoit rien. Supprimer le retire avec tous ses événements après confirmation.
Depuis l'API
Les applications connectées via l'API peuvent créer leurs propres endpoints
avec les endpoints /api/v1/hooks et une clé API disposant du scope
webhooks:manage. Ils apparaissent dans la liste avec un badge API, et
seuls leur nom et leur statut peuvent être modifiés ici. Ils n'ont ni Faire
tourner le secret ni Envoyer un test. Consultez
Clés API et accès développeur.