Webhooks entrants

📥 Webhooks entrants

Recevez des événements provenant de plateformes externes et attribuez des graines à vos clients automatiquement. Les webhooks entrants vous permettent de connecter n'importe quel outil tiers — applications de quiz, formulaires, plateformes d'avis, Zapier, Make, et plus — à votre programme de fidélité LoyaltyTree.

Comment ça fonctionne

Le système de webhook entrant utilise un modèle Sources & Codes :

1. Créer une Source — Une source représente une plateforme ou un outil externe (par exemple, "Typeform", "Zapier", "Mon Application de Quiz"). Chaque source obtient une URL de webhook unique et une clé secrète pour la sécurité.
2. Ajouter des Codes à la Source — Chaque code définit une action spécifique qui attribue des graines (par exemple, "quiz_completed", "form_submitted", "birthday_claimed"). Vous définissez combien de graines chaque code attribue, avec des limites optionnelles.
3. Envoyer des requêtes POST — Votre plateforme externe envoie une requête POST à l'URL du webhook avec le code et les informations du client. LoyaltyTree trouve ou crée le client et attribue les graines automatiquement.

Commencer

Étape 1 : Créer une Source de Webhook

Accédez à Boutiques → [Votre Boutique] → Intégrations → Webhooks entrants. Cliquez sur + Ajouter une Source et donnez-lui un nom qui décrit la plateforme externe (par exemple, "Quiz Typeform" ou "Automatisation Zapier").

Lorsque la source est créée, vous recevrez :

• URL de Webhook — Le point de terminaison auquel votre plateforme externe enverra des requêtes
• Secret de Webhook — Une clé secrète pour signer les requêtes (recommandée pour la sécurité)

Étape 2 : Ajouter des Codes

Chaque code représente une action spécifique que vous souhaitez récompenser. Cliquez sur + Ajouter un Code sur votre source pour en créer un.

Champ	Requis	Description
Code	Oui	La valeur exacte envoyée dans la charge utile du webhook (par exemple, quiz_completed). Cela doit correspondre à ce que votre plateforme externe envoie.
Nom d'affichage	Oui	Un nom convivial affiché dans le tableau de bord admin et l'historique des transactions (par exemple, "Quiz Complété").
Description	Non	Une note optionnelle pour votre équipe sur le moment où ce code est utilisé.
Montant des Graines	Oui	Combien de graines attribuer chaque fois que ce code est déclenché. Par défaut, c'est 1.
Max Graines/Client	Non	Le nombre maximum total de graines qu'un seul client peut gagner avec ce code. Laissez vide pour illimité. Une fois qu'un client atteint cette limite, d'autres appels de webhook pour lui renverront un succès mais attribueront 0 graines.
Temps de Recharge (heures)	Non	Heures minimales entre les récompenses pour le même client sur ce code. Empêche les abus en limitant la fréquence à laquelle un client peut gagner des graines. Laissez vide pour pas de temps de recharge.
Activé	—	Basculer pour activer ou désactiver ce code sans le supprimer. Les codes désactivés renvoient une erreur 403.

Codes & Limites Expliqués

Les codes et leurs limites fonctionnent ensemble pour vous donner un contrôle précis sur la manière dont les graines sont attribuées :

Montant des Graines

Chaque code a un montant de graines fixe. Chaque fois que le webhook est déclenché avec ce code, le client reçoit exactement ce nombre de graines. Par exemple, si vous définissez "quiz_completed" à 5 graines, chaque appel de webhook qualifié attribue 5 graines.

Max Graines par Client

Cela fixe un plafond à vie par client par code. C'est le total des graines que ce client peut gagner avec ce code spécifique, pas le nombre de fois qu'il peut le déclencher.

Temps de Recharge (Heures)

Fixe un temps d'attente minimum entre les récompenses de graines pour le même client sur le même code. Le minuteur de recharge commence à partir de la dernière récompense réussie.

Format de Requête

Envoyez une requête POST à votre URL de webhook avec le corps JSON suivant :

{
  "code": "your_code_here",
  "customer": {
    "email": "customer@example.com",
    "shopify_customer_id": "12345",
    "first_name": "Jane",
    "last_name": "Smith"
  },
  "metadata": {
    "quiz_score": 95,
    "source_page": "spring-quiz"
  }
}

* Au moins l'un de email ou shopify_customer_id est requis. L'e-mail est requis lorsque le client n'existe pas encore dans LoyaltyTree.

Vérification de la Signature HMAC (Recommandé)

Pour vérifier que les requêtes proviennent réellement de votre plateforme (et non de quelqu'un qui a trouvé votre URL de webhook), signez vos requêtes en utilisant HMAC-SHA256.

En-têtes de signature pris en charge (LoyaltyTree vérifie tous ces en-têtes) :

• X-Webhook-Signature
• X-Hub-Signature-256
• X-Signature

La valeur de la signature peut être soit le hachage hexadécimal brut, soit préfixée par sha256= (les deux formats sont acceptés).

Alternative : Authentification par Token Simple

Si la signature HMAC n'est pas possible dans votre plateforme, vous pouvez passer votre secret de webhook comme un token simple dans l'en-tête X-Token. LoyaltyTree le comparera directement à votre secret.

Exemple : Signature avec Node.js

const crypto = require('crypto');

const payload = JSON.stringify({
  code: 'quiz_completed',
  customer: { email: 'jane@example.com' }
});
const signature = crypto
  .createHmac('sha256', 'your_webhook_secret')
  .update(payload)
  .digest('hex');
fetch('https://loyaltytree.eco/webhooks/inbound/YOUR_SOURCE_ID', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Webhook-Signature': signature
  },
  body: payload
});

Exemple : Signature avec Python

import hmac, hashlib, json, requests

payload = json.dumps({
    "code": "quiz_completed",
    "customer": {"email": "jane@example.com"}
})
signature = hmac.new(
    b'your_webhook_secret',
    payload.encode('utf-8'),
    hashlib.sha256
).hexdigest()
requests.post(
    'https://loyaltytree.eco/webhooks/inbound/YOUR_SOURCE_ID',
    headers={
        'Content-Type': 'application/json',
        'X-Webhook-Signature': signature
    },
    data=payload
)

Exemple : Utilisation de cURL (pour les tests)

curl -X POST https://loyaltytree.eco/webhooks/inbound/YOUR_SOURCE_ID \
  -H "Content-Type: application/json" \
  -H "X-Token: your_webhook_secret" \
  -d '{"code":"quiz_completed","customer":{"email":"jane@example.com"}}'

Format de Réponse

Réponse Réussie (200)

{
  "success": true,
  "seeds_awarded": 5,
  "transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customer_id": "f0e1d2c3-b4a5-6789-0123-456789abcdef"
}

Réussi mais Limité (200)

Lorsque un temps de recharge ou une limite de graines maximum empêche l'attribution, vous obtenez toujours une réponse 200 mais avec 0 graines et une explication :

{
  "success": true,
  "seeds_awarded": 0,
  "message": "Temps de recharge actif. Réessayez dans 18 heure(s)."
}

// ou
{
  "success": true,
  "seeds_awarded": 0,
  "message": "Maximum de graines (15) déjà attribuées pour ce code."
}

Réponses d'Erreur

Exemples de Cas d'Utilisation

Connexion avec Zapier

Zapier est l'un des moyens les plus populaires de connecter LoyaltyTree avec des centaines d'autres applications. Nous construisons une intégration LoyaltyTree dédiée dans le Zapier App Store, ce qui facilitera encore plus la configuration — recherchez-la dans le marché Zapier.

En attendant, vous pouvez utiliser l'action Webhooks by Zapier pour vous connecter dès maintenant :

Connexion avec Make (Integromat)

Vous pouvez également utiliser le module HTTP / Faire une requête de Make pour envoyer des webhooks à LoyaltyTree. Configurez-le de la même manière que Zapier — définissez l'URL, ajoutez le corps JSON avec code et customer, et incluez votre secret dans l'en-tête X-Token.

Journaux de Webhook

Chaque appel de webhook entrant est enregistré et visible dans la section Webhooks entrants de votre page d'intégrations. Les journaux montrent :

• Horodatage – Quand le webhook a été reçu
• Source – Quelle source l'a reçu
• Statut – Succès ou échec
• Détails – Code utilisé, graines attribuées, ou message d'erreur
• Charge Utile – Le corps complet de la requête (crypté au repos)

Utilisez les journaux pour vérifier que votre intégration fonctionne correctement et pour résoudre tout problème.

Dépannage

Sécurité

• Chaque source obtient un secret de webhook unique de 64 caractères, généré automatiquement et crypté au repos
• Les secrets peuvent être régénérés à tout moment à partir des paramètres de la source (l'ancien secret cesse de fonctionner immédiatement)
• Les charges utiles de requête sont cryptées dans les journaux pour la confidentialité
• La vérification de signature utilise une comparaison sécurisée par temps pour prévenir les attaques par temporisation
• Les sources et les codes peuvent être désactivés individuellement sans les supprimer