Aller au contenu

Guide

Configurer des webhooks

Automatisations et intégrations · 7 min de lecture

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. Si votre offre ne les inclut plus, les livraisons s'arrêtent. Vos webhooks sont conservés et reprennent lorsque vous passez à une offre supérieure.

Créer un point de terminaison de webhook

  1. Accédez à Admin → Paramètres → Intégrations et ouvrez l'onglet Webhooks.
  2. Cliquez sur Ajouter un webhook.
  3. Renseignez Nom et une URL du point de terminaison HTTPS.
  4. Vous pouvez générer un secret de signature à copier chez le destinataire. Voir la vérification ci-dessous.
  5. Sélectionnez explicitement au moins un événement. Recherchez ou choisissez par catégorie ; Documentation de l’événement ouvre sa référence.
  6. Cliquez sur Créer un webhook. Les nouveaux webhooks sont enregistrés inactifs.
  7. Enregistrez, envoyez un test puis activez lorsque le destinataire est prêt.

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, Membre parti, 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.

Dans une ancienne configuration, une liste vide signifie tous les événements. Conservez-la ou choisissez des abonnements explicites. Les événements indisponibles restent lors d'autres modifications ; changer les abonnements exige de retirer les anciens et d'en choisir au moins un actuel. Si le catalogue ne charge pas, réessayez avant de choisir ou tester.

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.

Fonctionnement de l'événement de webhook « Membre parti »

Membre parti est envoyé une fois lorsqu'une personne cesse d'être membre de votre communauté, pour que vous puissiez la retirer de votre CRM ou de votre liste de diffusion. Il se déclenche lorsque :

  • un administrateur utilise Retirer de la communauté ou Anonymiser le membre ;
  • le membre supprime son compte. Une suppression programmée compte à la fin de la période de réflexion de 30 jours, pas au moment de la demande ; si le membre l'annule, rien n'est envoyé ;
  • votre politique de conservation des données efface un membre inactif. Elle s'exécute chaque nuit, donc de nombreux événements peuvent arriver en même temps.

Chaque événement contient le nom d'utilisateur et l'e-mail du membre d'avant son départ, même si son compte a été anonymisé, pour que vous puissiez le retrouver dans votre propre système. Il indique aussi comment le membre est parti et, si un administrateur l'a retiré ou anonymisé, de quel administrateur il s'agit. Si l'administrateur a rédigé une Note interne (facultatif) en retirant le membre, la note est également incluse.

Membre parti n'est pas envoyé lorsqu'un membre désactive son compte, est suspendu ou banni (c'est alors Membre suspendu), quitte un espace ou n'a jamais terminé son inscription. Les groupes d'accès d'un membre qui part n'envoient pas Membre retiré d’un groupe d’accès.

Les applications connectées dont la carte affiche Tous les événements transmis commencent aussi à envoyer Membre parti, y compris vers des canaux Slack ou Discord. Pour l'exclure, choisissez Modifier les paramètres et sélectionnez les événements à transmettre. Consultez Présentation des intégrations : API, webhooks et Zapier.

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 :

  1. Lisez le corps brut de la requête exactement tel que reçu, avant d'analyser le JSON.
  2. Construisez la chaîne signée : la valeur de X-Mateflow-Timestamp, un point (.), puis le corps brut.
  3. Calculez un HMAC-SHA256 de cette chaîne avec votre secret comme clé, et encodez-le en hexadécimal.
  4. Comparez-le avec la partie de X-Mateflow-Signature qui suit sha256=, en utilisant une comparaison à temps constant. Rejetez la requête s'ils diffèrent.
  5. Si vous le souhaitez, rejetez les requêtes dont l'horodatage date de plus de quelques minutes, pour bloquer les rejeux.

Les requêtes envoyées par l'action Déclencher un webhook d'une règle d'automatisation sont signées de la même manière lorsque la règle a un 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

Enregistrez avant de tester ou d'ouvrir les journaux. Dans les actions, ouvrez le test, choisissez un événement abonné compatible avec les exemples puis cliquez sur Envoyer un test. L'exemple porte test=true et part vers l'URL enregistrée, même si le webhook est inactif. Le destinataire doit reconnaître les tests. Un 2xx confirme uniquement la réception HTTP, pas la fin de votre traitement. Vérifiez statut, réponse et journaux.

Activez après test ; désactiver suspend les livraisons réelles. Modifier un webhook actif prend effet à l'enregistrement. La suppression efface aussi ses journaux définitivement. Après modification, l'ancien test expire : testez la configuration enregistrée à nouveau.

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. Pour voir les livraisons d'un webhook, utilisez Filtrer par webhook. 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 après 1 minute, 10 minutes, 1 heure et 6 heures. Les réponses HTTP 429 et 408 sont aussi réessayées ; les autres réponses 4xx ne le sont pas. Lorsque les tentatives sont épuisées, ou en cas de réponse 4xx non réessayée, le propriétaire et les administrateurs reçoivent un e-mail, au maximum une fois par jour pour chaque webhook.

Pour envoyer vous-même une livraison de nouveau, cliquez sur Renvoyer dans sa ligne. Le même corps est envoyé, signé de nouveau, à l'URL actuelle du webhook. Actualisez pour voir le résultat sous forme de nouvelle ligne. Un webhook supprimé ou désactivé ne peut pas renvoyer. Chaque tentative a sa propre ligne. Une nouvelle tentative automatique reçoit un nouvel ID de livraison, Renvoyer conserve celui d'origine et 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 et des exemples de code, cliquez sur Ouvrir la documentation dans la carte Référence des webhooks pour les développeurs de l'onglet Webhooks, ou rendez-vous sur mateflow.com/developers/webhooks. Vous pouvez envoyer ce lien à votre équipe de développement.

Les journaux se filtrent par événement, résultat, webhook, dates, Source et Plateforme. Les métriques suivent le périmètre et la période choisis ; elles comptent les tentatives HTTP, tests et renvois inclus, pas les événements uniques. Historique et conservation sont indiqués. Les totaux de configuration sont un instantané distinct : actifs, inactifs et actifs avec échecs récents.

Articles associés

Ce guide vous a-t-il été utile ?

Retour aux guides

Vous ne trouvez pas ce qu'il vous faut ?

Si vous êtes membre d'une communauté, ses administrateurs sont les mieux placés pour vous aider. Si vous créez ou gérez une communauté sur Mateflow, notre équipe peut vous aider.