Comment fonctionnent les webhooks Kooneo : événements, données envoyées et configuration

Les webhooks Kooneo envoient automatiquement les données d’un événement vers un outil externe : paiement, commande, remboursement ou changement d’abonnement. Ils peuvent aussi transmettre un tag personnalisé pour suivre l’origine d’une vente.

À quoi sert un webhook ?

Un webhook est une notification automatique envoyée par Kooneo vers une URL que vous avez définie. L’outil qui reçoit les données peut ensuite enregistrer la vente, ajouter un contact ou déclencher une automatisation.

Quels événements peut-on transmettre ?

  • Nouveau paiement ou premier paiement récurrent
  • Nouveau paiement récurrent
  • Paiement récurrent échoué
  • Abonnement annulé
  • Remboursement
  • Nouvelle commande

Comment configurer un webhook ?

  1. Récupérez l’URL de réception
  • Cette URL est fournie par l’outil ou la plateforme qui recevra les données.
  1. Ajoutez le webhook dans Kooneo
  • Dans le menu principal, cliquez sur Outils.
  • Dans le menu de gauche, cliquez sur Webhooks.
  • Ajoutez l’URL de réception.
  • Sélectionnez les événements à transmettre.
  1. Envoyez un test
  • Utilisez le bouton de test disponible dans Outils puis Webhooks.
  • Vérifiez la structure exacte reçue par votre outil avant de traiter de vraies ventes.

💡 Le test reste la méthode la plus fiable pour vérifier les champs disponibles pour chaque événement.

Quelles données sont envoyées ?

Les données sont envoyées au format JSON dans le corps de la requête. Selon l’événement, elles comprennent notamment :

  • type : type d’événement envoyé.
  • customer : informations du client.
  • invoice : montant, devise, facture, commande, transaction, mode de paiement, produits et tags.
  • subscription : informations de l’abonnement lorsqu’il est concerné.
  • affiliate : informations de l’affilié lorsqu’une attribution affiliée existe.
Information recherchée Champ
Référence du produit invoice.products[].reference
Numéro de commande invoice.order_id
Identifiant de transaction invoice.transaction_id
Tag personnalisé nommé origin invoice.tags.origin

Exemple simplifié :

{
  "type": "new_payment",
  "invoice": {
    "order_id": 98211,
    "transaction_id": "transaction_exemple",
    "products": [
      {
        "reference": "CONSULT-01"
      }
    ],
    "tags": {
      "origin": "a24f66771"
    }
  }
}

Comment transmettre une valeur personnalisée ?

Créez d’abord le tag dans Kooneo. Ajoutez ensuite sa valeur à l’URL de la page ou du formulaire de commande.

?tag_origin=a24f66771

Pour un tag nommé origin, la valeur reçue dans le webhook se trouve dans invoice.tags.origin.

La procédure complète se trouve dans l’article Créer et utiliser les tags.

⚠️ Les tags sont attachés au client, pas à une commande précise. Une nouvelle valeur peut remplacer la précédente.

  • Enregistrez la valeur dès la réception du webhook pour conserver un historique fiable par vente.
  • Envoyez toujours le paramètre, même sans source particulière.
  • Utilisez par exemple tag_origin=direct lorsqu’aucun partenaire ou aucune campagne ne doit être attribué.

Que contient le webhook de remboursement ?

L’événement de remboursement contient également le bloc invoice. Utilisez notamment invoice.order_id et invoice.transaction_id pour rapprocher le remboursement de la vente enregistrée.

Le bloc invoice.tags permet aussi de récupérer le tag transmis.

Peut-on créer un webhook par produit ?

Non. Les webhooks se configurent par type d’événement, pas par produit.

Votre outil peut toutefois filtrer les messages reçus avec l’identifiant ou la référence disponible dans invoice.products.

Peut-on relire une commande avec l’API ?

Non, ce n’est pas possible actuellement. L’API publique Kooneo couvre la gestion des membres, mais ne propose pas de route permettant de retrouver une commande à partir de son numéro ou de son identifiant de transaction.

Votre outil doit donc conserver les données reçues dans le webhook. Traitez chaque événement de manière à ne pas enregistrer deux fois la même opération s’il est renvoyé.

Que se passe-t-il en cas d’échec ?

Une réponse HTTP comprise entre 200 et 299 confirme à Kooneo que le webhook a bien été reçu.

En cas d’échec, Kooneo effectue jusqu’à 5 tentatives, avec un espacement croissant pouvant aller jusqu’à 24 heures.

⚠️ Le journal des webhooks n’est pas encore accessible dans l’interface. Vérifiez la réception dans les journaux de votre outil externe et utilisez la fonction de test Kooneo.

Comment vérifier que le webhook vient de Kooneo ?

Les webhooks Kooneo ne sont pas signés actuellement. Il n’existe donc pas encore de signature HMAC ou de clé secrète ajoutée automatiquement à chaque envoi.

Vous pouvez renforcer le contrôle de deux façons :

  • Ajoutez un secret long et aléatoire dans l’URL du webhook, puis vérifiez sa présence à la réception.
https://votre-site.fr/webhooks/kooneo?k=<secret-long-et-aleatoire>
  • Filtrez les appels selon les adresses IP utilisées par Kooneo après avoir demandé la liste actuelle au support.

Récapitulatif

Question Réponse
Données envoyées ✅ JSON dans le corps de la requête
Référence produit ✅ Dans invoice.products
Tag personnalisé ✅ Dans invoice.tags
Remboursement ✅ Événement avec le bloc invoice
Nouvelle tentative après un échec ✅ Jusqu’à 5 tentatives sur 24 heures
Webhook par produit ❌ Non, filtrage à faire côté outil externe
Relecture d’une commande par l’API ❌ Non
Signature HMAC ❌ Pas actuellement

Les derniers tutoriels