Un webhook envoie une requête HTTPS depuis Mateflow vers une URL que vous contrôlez chaque fois qu'il se passe quelque chose dans votre communauté, comme l'arrivée d'un nouveau membre ou la réception d'un paiement. Utilisez les webhooks pour garder un CRM, un outil d'e-mailing ou votre propre application synchronisés. Vous les configurez dans Admin → Paramètres → Intégrations → Webhooks.
Qui peut le faire : Les propriétaires et les administrateurs. · Où : Sur le web (console d'administration). · Offre : Les webhooks, ainsi que le nombre que vous pouvez en créer, dépendent de votre offre de la plateforme.
Créer un point de terminaison de webhook
- Accédez à Admin → Paramètres → Intégrations et ouvrez l'onglet Webhooks.
- Cliquez sur Ajouter un webhook.
- Saisissez un Nom (moins de 100 caractères) et l'URL du point de terminaison. L'URL doit utiliser HTTPS.
- Facultatif, mais recommandé : sous Secret (optionnel), cliquez sur le bouton de génération (Générer un secret) et copiez le secret pour votre serveur. Consultez la section sur les signatures ci-dessous.
- Sous Événements, cochez les événements à envoyer. Cochez le nom d'une catégorie pour sélectionner tous ses événements.
- Laissez Actif activé pour que le webhook commence à recevoir des événements.
- Cliquez sur Créer un webhook.
Si le bouton Ajouter un webhook affiche une invitation à passer à une offre supérieure, votre offre n'inclut pas les webhooks ou vous avez atteint la limite de webhooks de votre offre. Consultez Consulter l'utilisation et les limites de votre offre.
Événements de webhook auxquels vous pouvez vous abonner
| Catégorie | Événements |
|---|---|
| Membres | Membre inscrit, Rôle modifié, Membre suspendu (aussi envoyé pour les bannissements), Membre réintégré, Membre ajouté à un groupe d’accès, Membre retiré d’un groupe d’accès |
| Contenu | Publication créée, Commentaire créé, Publication supprimée, Commentaire supprimé |
| Paiements | Paiement reçu, Paiement échoué, Abonnement créé, Abonnement renouvelé, Abonnement annulé, Remboursement émis |
Les webhooks plus anciens peuvent afficher des événements qui ne sont plus disponibles. Vous pouvez les retirer, mais pas les rajouter.
Fonctionnement des événements de webhook liés aux groupes d'accès
Membre ajouté à un groupe d’accès et Membre retiré d’un groupe d’accès (les groupes d'accès étaient auparavant appelés niveaux de membres) se déclenchent lorsque les groupes d'un membre changent réellement. Chaque événement concerne un membre et un groupe, et inclut le nom d'utilisateur et l'e-mail du membre, le nom du groupe et l'origine du changement : un administrateur, un abonnement, une invitation, le groupe d'accès par défaut ou un groupe supprimé.
- Aucun événement de groupe d'accès n'est envoyé avant Membre inscrit : le groupe par défaut attribué à un nouveau membre lors de son inscription n'est donc pas annoncé, pas plus que les changements survenus pendant qu'un membre attend son approbation.
- La suppression d'un groupe d'accès envoie un événement de retrait pour chaque membre qui en faisait partie. Ces événements, ainsi que ceux liés à la définition d'un groupe par défaut, peuvent arriver quelques minutes plus tard.
- Retirer un groupe accordé par un abonnement envoie un retrait puis un ajout, car l'abonnement le rajoute aussitôt. Consultez Ajouter ou retirer le groupe d'accès d'un membre.
Vérifier les signatures des webhooks avec la clé de signature
Lorsqu'un webhook a un secret, Mateflow signe chaque requête avec HMAC-SHA256 pour que votre serveur puisse vérifier qu'elle provient de Mateflow et n'a pas été modifiée (vérification de signature). Chaque requête comporte deux en-têtes :
X-Mateflow-Timestamp: le moment où la requête a été envoyée, en secondes Unix.X-Mateflow-Signature:sha256=suivi de la signature encodée en hexadécimal.
Pour vérifier une requête sur votre serveur :
- Lisez le corps brut de la requête exactement tel que reçu, avant d'analyser le JSON.
- Construisez la chaîne signée : la valeur de
X-Mateflow-Timestamp, un point (.), puis le corps brut. - Calculez un HMAC-SHA256 de cette chaîne avec votre secret comme clé, et encodez-le en hexadécimal.
- Comparez-le avec la partie de
X-Mateflow-Signaturequi suitsha256=, en utilisant une comparaison à temps constant. Rejetez la requête s'ils diffèrent. - Si vous le souhaitez, rejetez les requêtes dont l'horodatage date de plus de quelques minutes, pour bloquer les rejeux.
Pendant une période de transition, les requêtes contiennent aussi le secret lui-même dans un en-tête X-Webhook-Secret. Vérifiez la signature plutôt que de vous fier à cet en-tête.
Les requêtes envoyées par l'action Trigger webhook d'une règle d'automatisation fonctionnent différemment : elles ne sont pas signées, et le secret de la règle est envoyé tel quel dans l'en-tête X-Webhook-Secret. Consultez Automatiser des tâches avec des règles.
Une fois enregistré, le secret est masqué. Pour le conserver, laissez le champ vide lorsque vous modifiez le webhook. Pour le renouveler, générez-en un nouveau et mettez à jour votre serveur en même temps.
Tester, suspendre, modifier ou supprimer un webhook
Dans le menu Actions du webhook :
- Tester le webhook envoie une requête de test à votre point de terminaison.
- Désactiver arrête les livraisons sans supprimer le webhook ; Activer le réactive.
- Modifier change son nom, son URL, son secret ou ses événements.
- Supprimer retire le webhook et tous ses journaux de livraison. Cette action est irréversible.
La liste affiche pour chaque webhook son Statut, son Dernier déclenchement et le nombre de Succès et d'Échec. Un webhook affiche un statut d'erreur lorsque des livraisons récentes ont échoué.
Vérifier les livraisons et les nouvelles tentatives des webhooks
Ouvrez l'onglet Journaux de livraison pour voir chaque requête, son Statut HTTP, sa Durée et sa Source. Cliquez sur Afficher les détails pour voir la Charge utile de la requête et le Corps de la réponse complets. Les journaux de livraison sont conservés 30 jours.
Lorsqu'une livraison échoue, Mateflow la réessaie automatiquement, jusqu'à 3 fois. Il n'existe pas de bouton pour renvoyer vous-même une livraison. Chaque tentative a sa propre ligne et un nouvel ID de livraison, tandis que l'ID d'événement reste le même : les lignes qui partagent un ID d'événement sont donc des tentatives pour un même événement. Les livraisons peuvent arriver plusieurs fois ou dans le désordre : votre serveur doit donc dédoublonner à partir de l'ID d'événement. Pour les champs de la charge utile, consultez la documentation pour les développeurs sur mateflow.com/developers.
Articles associés
Ce guide vous a-t-il été utile ?