Webhooks – Comment automatiser les événements Perkstar avec des notifications API en temps réel
Découvrez comment configurer des webhooks pour l'automatisation des événements en temps réel. Guide complet pour créer des points de terminaison de webhook, s'abonner à des types d'événements, recevoir des charges utiles JSON, mettre en œuvre la vérification de sécurité, tester les livraisons et résoudre les problèmes de webhook. Vue d'ensemble
Les webhooks
permettent une automatisation en temps réel basée sur les événements en envoyant des notifications instantanées de Perkstar à vos propres systèmes ou applications tierces chaque fois que des événements spécifiques se produisent. Contrairement aux intégrations traditionnelles qui interrogent les modifications selon un calendrier, les webhooks vous transmettent des données immédiatement lorsque quelque chose se produit, permettant des réactions instantanées et une automatisation transparente.
Ce que vous pouvez faire avec les webhooks :
Recevez des notifications en temps réel lorsque les clients effectuent des actions (s'inscrire, ajouter une carte, effectuer un achat)
Déclenchez des flux de travail automatisés dans vos propres systèmes en fonction des événements de fidélité
Synchronisez instantanément les données de fidélité avec des applications ou des bases de données personnalisées
Créez des intégrations avancées avec des plates-formes qui ne sont pas prises en charge nativement
Créer une logique métier personnalisée qui répond à l'activité du programme de fidélisation
Surveillez tous les événements de fidélité en temps réel à des fins d'analyse ou d'alerte Astuce
: Les Webhooks éliminent les retards et le travail manuel en transmettant les informations à vos systèmes dès que des événements se produisent. Au lieu de rechercher des mises à jour toutes les heures ou tous les jours, vos applications reçoivent des notifications instantanées, permettant un engagement client immédiat, des rapports en temps réel et des systèmes synchronisés sur l'ensemble de votre pile technologique d'entreprise.
Qui doit utiliser les webhooks : Développeurs
: Création d'intégrations et d'automatisation personnalisées Équipes techniques
: Implémentation d'une automatisation avancée des flux de travail Administrateurs
IT : Connexion de Perkstar à des systèmes propriétaires
Utilisateurs avancés : Création d'une logique métier personnalisée au-delà des intégrations standard
Connaissances techniques requises :
Compréhension des HTTP/HTTPS et REST API
Possibilité de recevoir et d'analyser les données JSON
Compétences de base en programmation (tout langage prenant en charge les requêtes HTTP)
Accès à un serveur Web ou à une fonction cloud pour recevoir des appels webhook
Avant de commencer Exigences
:
Compte Perkstar actif
Autorisations du propriétaire du compte ou de l'administrateur Prise en charge du Webhook
incluse dans votre plan d'abonnement (consultez la section Plan)
Connaissance technique des API et du développement Web
Ce dont vous aurez besoin :
Infrastructure technique :
Un point de terminaison HTTPS accessible au public (URL) pour recevoir des données de webhook
Serveur Web, fonction cloud ou service webhook (Zapier, Make, n8n)
Capacité à analyser les charges utiles JSON
(Recommandé) Vérification de la signature Webhook pour la sécurité Configuration du développement
:
L'environnement de test est distinct de la production Système de journalisation
pour suivre les webhooks entrants
Gestion des erreurs et logique de nouvelle tentative
Surveillance des alertes en cas de pannes de webhook
Comprendre les webhooks et les intégrations Webhooks
:
Notifications push en temps réel
Vous écrivez du code personnalisé pour gérer les événements
Flexibilité et personnalisation maximales
Nécessite une mise en œuvre technique
Parfait pour : systèmes personnalisés, flux de travail uniques, exigences en temps réel Intégrations prédéfinies
:
Connexions préconfigurées aux plateformes populaires
Aucun codage requis
Limité aux intégrations disponibles
Configuration plus simple, mais moins flexible
Idéal pour : cas d'utilisation standard, utilisateurs non techniques, plates-formes communes
Utilisez des webhooks lorsque :
Vous avez besoin de notifications d'événements en temps réel
Vous intégrez des systèmes personnalisés ou propriétaires
Les intégrations prédéfinies ne répondent pas à vos besoins
Vous souhaitez un contrôle total sur le traitement des données
Vous créez des workflows d'automatisation avancés
Accéder à la section Webhooks
Comment accéder aux webhooks
Depuis votre tableau de bord :
Connectez-vous à votre compte Perkstar
Cliquez sur Paramètres (icône ⚙️) dans le menu de gauche
Cliquez sur l'onglet Webhooks en haut de l'écran Paramètres
Note: L'écran Webhooks affiche tous les outils et options de gestion des webhooks.
Disposition de l'écran des webhooks
La section Webhooks contient deux zones principales :
Liste des webhooks (tableau) :
Affiche tous les webhooks existants
Affiche URL, l'état et le nombre d'événements pour chaque webhook
Aperçu rapide de toutes les configurations de webhooks actives
Bouton Ajouter un Webhook :
Crée de nouvelles configurations de webhook
Ouvre la fenêtre contextuelle de création de webhook
Comprendre la liste des webhooks
Colonnes du tableau Webhooks
Tous les webhooks configurés apparaissent dans un tableau avec les informations suivantes :
URL :
Le point de terminaison qui reçoit les notifications de webhook
Adresse HTTPS complète de votre serveur ou service de réception
Exemple : https://api.yourcompany.com/webhooks/perkstar
Statut:
État opérationnel actuel du webhook
Activé: Le Webhook est actif et envoie des notifications
Désactivé: Le Webhook est en pause et n'envoie pas de notifications
Vous permet de désactiver temporairement les webhooks sans les supprimer
Nombre d'événements :
Nombre de types d'événements auxquels ce webhook est abonné
Nombre plus élevé = le webhook reçoit plus de types de notifications
Cliquez sur le webhook pour voir quels événements spécifiques sont activés
Affichage des détails du webhook
Pour afficher ou modifier un webhook existant :
Localisez le webhook dans la liste des Webhooks
Cliquez sur la ligne du webhook
La fenêtre contextuelle des détails du webhook s'ouvre et affiche la configuration complète
Détails affichés :
URL complet
Tous les types d'événements abonnés avec des cases à cocher
État actuel (bascule Activé/Désactivé)
Date de création
Informations sur la dernière livraison (si disponible)
Options de modification et de suppression
Créer un nouveau webhook
Étape 1 : Préparez votre point de terminaison
Avertissement: Avant de créer un webhook dans Perkstar, assurez-vous que votre point de terminaison de réception est prêt.
Votre point de terminaison doit :
Être accessible au public via HTTPS (et non HTTP)
Accepter les demandes HTTP POST
Renvoyez le code d'état 200 pour une réception réussie
Répondez dans les 5 à 10 secondes (traitement rapide)
Analyser le corps de la requête JSON
Gérer les tentatives de webhook avec élégance
Recommandations de sécurité :
Utilisez HTTPS (obligatoire pour la sécurité)
Valider les signatures de webhook (si fournies par Perkstar)
Mettre en œuvre une limitation du débit pour éviter les abus
Enregistrez tous les webhooks entrants pour le débogage
Utilisez des règles de pare-feu pour restreindre l'accès si possible
Exemple de configuration de point de terminaison (Node.js/Express) :
Étape 2 : Créer le Webhook dans Perkstar
Pour ajouter un nouveau webhook :
Accédez à Paramètres → onglet Webhooks
Cliquez sur le bouton Ajouter un webhook
La fenêtre contextuelle Ajouter un webhook s'ouvre
Étape 3 : Configurer les paramètres du Webhook
Saisissez le webhook URL :
Dans le champ URL en haut de la fenêtre contextuelle, saisissez l'adresse de votre point de terminaison
Doit être un HTTPS URL complet
Exemple : https://api.yourcompany.com/webhooks/perkstar
Vérifiez à nouveau les fautes de frappe : les URL incorrects échoueront
Sélectionnez les types d'événements :
Sous le champ URL, vous verrez une liste des types d'événements disponibles
Chaque type d'événement a une case à cocher
Cochez la case pour chaque événement que vous souhaitez recevoir
Abonnez-vous uniquement aux événements dont vous avez réellement besoin (réduit le trafic inutile)
Étape 4 : Activer le Webhook
Définir l'état du webhook :
Localisez le bouton bascule Statut dans la fenêtre contextuelle
Basculer sur Activé (position ON)
Si vous souhaitez enregistrer le webhook mais ne pas l'activer encore, laissez-le désactivé
Webhooks activés :
Commencez immédiatement à envoyer des notifications
Se déclenchera pour tous les événements souscrits qui se produisent
Peut être désactivé ultérieurement sans supprimer
Webhooks désactivés :
La configuration est enregistrée mais aucune notification n'est envoyée
Utile pour les tests ou les pauses temporaires
Peut être activé à tout moment
Étape 5 : Enregistrez le webhook
Pour terminer la création du webhook :
Vérifiez tous les paramètres (URL, événements, statut)
Cliquez sur le bouton Ajouter un webhook en bas de la fenêtre contextuelle
Le Webhook est créé et ajouté à la liste des Webhooks
Infos : S'il est activé, le webhook commence immédiatement à envoyer des notifications.
Après création :
Le nouveau webhook apparaît dans le tableau de la liste des Webhooks
La colonne Nombre d'événements affiche le nombre d'événements abonnés
La colonne d'état indique Activé ou Désactivé
Testez le webhook en déclenchant un événement souscrit
Types d'événements disponibles
Comprendre les types d'événements
Infos : Les types d'événements représentent des actions ou des changements spécifiques qui se produisent dans votre compte Perkstar. Lorsque vous vous abonnez à un type d'événement, votre webhook reçoit une notification chaque fois que cet événement se produit.
Types d'événements courants
Événements clients :
client.created - Un nouveau client s'inscrit ou est ajouté
client.updated - Modifications des informations sur le profil client
client.deleted - Le client est supprimé du système
Événements de carte de fidélité :
card.installed - Le client ajoute une carte au portefeuille numérique
card.updated - Informations sur la carte ou modifications de conception
card.deleted - Le client retire la carte du portefeuille
Événements de transactions :
transaction.created - Points, timbres ou remise ajoutés
transaction.completed - Transaction finalisée et confirmée
transaction.reversed - Transaction annulée ou points déduits
Événements de récompense :
récompense.issued - Le client gagne une récompense
récompense.redeemed - Le client utilise/réclame une récompense
récompense.expired - La récompense non réclamée expire
Événements de notification push :
push.sent - Notification push envoyée au client
push.opened - Le client ouvre la notification push
push.failed - Échec de l'envoi des notifications push
Événements de commentaires :
retours.received - Le client soumet des commentaires ou une note
retours.updated - Les commentaires sont modifiés
Événements de référence :
reference.created - Nouvelle référence initiée
reference.completed - Le parrainage se convertit avec succès
Note: Les types d'événements disponibles peuvent varier selon le forfait et la version de Perkstar. Consultez la fenêtre contextuelle Ajouter un webhook pour connaître la liste complète des événements disponibles pour votre compte.
Choisir les événements auxquels s'abonner
Bonnes pratiques pour la sélection d'événements :
Commencez minimalement :
Abonnez-vous uniquement aux événements dont vous avez activement besoin
Moins d'événements = logique plus simple et moins de données à traiter
Vous pouvez toujours ajouter d'autres événements plus tard
Combinaisons de départ courantes :
Suivi de l'activité des clients : client.créé, transaction.terminée
Synchronisation CRM en temps réel : client.créé, client.mis à jour, transaction.créé
Automatisation des récompenses : récompense.émise, récompense.rachetée
Suivi des engagements : carte.installée, poussée.ouverte, commentaires.reçus
Tenez compte du volume de l'événement :
transaction.created peut se déclencher plusieurs fois par jour (volume élevé)
client.created se déclenche moins fréquemment (volume inférieur)
Assurez-vous que votre système peut gérer le volume de webhook attendu
Événements liés au groupe :
Conseil: Si vous avez besoin d’un événement du cycle de vie, vous avez souvent besoin de l’ensemble complet. Exemple : client.created, client.updated, client.deleted ensemble. Cela garantit que votre système reste synchronisé avec toutes les modifications.
Structure de la charge utile du webhook
Quelles données sont envoyées
Infos : Lorsqu'un événement se produit, Perkstar envoie une requête HTTP POST à votre webhook URL contenant les données JSON sur l'événement.
Structure de charge utile standard :
Champs de charge utile courants
event_type (chaîne) :
Identifie quel événement s'est produit
Exemple : "client.créé", "transaction.terminée"
Utilisez-le pour acheminer les webhooks vers les gestionnaires appropriés
event_id (chaîne) :
Identifiant unique pour cet événement spécifique
À utiliser pour l'idempotence (détection des livraisons en double)
Inclure dans les journaux pour le dépannage
horodatage (ISO 8601 dateheure) :
Quand l'événement s'est produit
Exemple : "2025-10-14T15:30:00Z"
Fuseau horaire UTC
account_id (chaîne) :
Votre identifiant de compte Perkstar
Utile si un point de terminaison gère plusieurs comptes
Peut être utilisé pour acheminer vers la base de données/locataire correct
données (objet):
Détails spécifiques à l'événement
La structure varie selon le type d'événement
Contient la charge utile réelle (informations client, détails de la transaction, etc.)
Exemples de charges utiles par type d'événement
client.créé :
transaction.terminée :
récompense.émise :
Gestion des charges utiles des Webhooks
Meilleures pratiques pour le traitement des charges utiles :
Validez la structure de la charge utile :
Vérifiez que les champs obligatoires existent
Vérifier que les types de données sont corrects
Gérez les champs manquants ou inattendus avec élégance
Utilisez event_id pour l'idempotence :
Stocker les event_ids traités pour détecter les doublons
Si vous recevez le même event_id deux fois, ignorez le traitement
Empêche les actions en double (double facturation, enregistrements en double)
Analysez soigneusement les données :
Utilisez l'analyseur JSON adapté à votre langue
Gérer les erreurs d’analyse (JSON mal formé)
Valider les données avant de les utiliser dans la logique métier
Répondez rapidement :
Avertissement: Renvoyez le statut 200 immédiatement après réception. Traitez le webhook de manière asynchrone (file d’attente pour le traitement). N'effectuez pas de longues opérations avant de répondre. Perkstar réessayera si vous ne répondez pas rapidement.
Exemple de contrôle d'idempotence (pseudocode) :
Tester vos webhooks
Pourquoi les tests sont essentiels
Avant de vous fier aux webhooks en production :
Vérifiez que votre point de terminaison reçoit correctement les webhooks
Assurez-vous que l’analyse de la charge utile fonctionne comme prévu
Confirmez que votre logique métier gère correctement les événements
Identifiez et résolvez tout problème avant qu’il n’affecte les clients
Stratégies de test
1. Utilisez les outils de test des webhooks :
Webhook.site : service gratuit qui affiche les webhooks entrants
RequestBin : point de terminaison temporaire pour inspecter les charges utiles des webhooks
Postman : envoyez manuellement des demandes de test à votre point de terminaison
2. Créez des événements de test dans Perkstar :
Enregistrez un client test
Effectuer une transaction test
Déclencher les événements auxquels vous êtes abonné
Vérifiez que les webhooks arrivent à votre point de terminaison
3. Vérifiez vos journaux :
Examiner les journaux du serveur pour les requêtes POST entrantes
Vérifier la structure de la charge utile JSON
Vérifiez les erreurs d'analyse
Confirmer que la logique métier s'exécute correctement
4. Testez les scénarios d’erreur :
Que se passe-t-il si votre point de terminaison est en panne ?
Comment votre système gère-t-il les charges utiles mal formées ?
L'idempotence fonctionne-t-elle (envoyer un event_id en double) ?
Votre système peut-il se remettre de pannes temporaires ?
Utilisation de Webhook.site pour les tests
Test rapide avant production :
Allez sur https://webhook.site
Copiez le URL unique fourni
Dans Perkstar, créez un webhook de test avec ce URL
Abonnez-vous à un événement comme client.created
Créer un client test dans Perkstar
Vérifiez webhook.site : vous verrez la charge utile du webhook
Examinez la structure et les champs de données JSON
Avantages:
Aucun codage requis
Voir les webhooks en temps réel
Inspecter les en-têtes et la charge utile
Parfait pour comprendre la structure de la charge utile avant de construire
Gestion des webhooks existants
Modifier un webhook
Pour modifier un webhook existant :
Accédez à Paramètres → onglet Webhooks
Cliquez sur le webhook que vous souhaitez modifier dans la liste
La fenêtre contextuelle des détails du webhook s'ouvre
Apportez vos modifications :
Mettre à jour le URL si le point de terminaison a été modifié
Cocher ou décocher les types d'événements
Basculer l'état (Activer/Désactiver)
Cliquez sur le bouton Enregistrer ou Mettre à jour
Infos : Les modifications prennent effet immédiatement.
Quand modifier les webhooks :
Modifications du point de terminaison URL (nouveau serveur, service différent)
Vous avez besoin de types d'événements supplémentaires
Vous souhaitez réduire les événements pour réduire le volume
Désactivation temporaire pour maintenance
Activation et désactivation des webhooks
Pour désactiver temporairement un webhook :
Cliquez sur le webhook dans la liste
Basculez le commutateur d'état sur Désactivé
Cliquez sur Enregistrer
Note: La configuration du Webhook est conservée mais aucune notification n'est envoyée.
Pour réactiver un webhook :
Cliquez sur le webhook
Basculer le statut sur Activé
Cliquez sur Enregistrer
Conseil: Webhook reprend immédiatement l'envoi de notifications.
Cas d'utilisation pour la désactivation :
Maintenance des points de terminaison ou mises à jour du serveur
Dépannage des problèmes de webhooks
Pause temporaire pendant les tests
Fermeture saisonnière d'entreprise
Avantages par rapport à la suppression :
La configuration est conservée (URL, événements)
Facile à réactiver plus tard
Pas besoin de reconfigurer à partir de zéro
Peut désactiver/activer plusieurs fois
Supprimer un webhook
Pour supprimer définitivement un webhook :
Cliquez sur le webhook dans la liste
Localisez le bouton Supprimer dans la fenêtre contextuelle des détails
Confirmez la suppression lorsque vous y êtes invité
Le Webhook est supprimé de la liste
Après suppression :
Webhook arrête immédiatement d'envoyer des notifications
La configuration ne peut pas être récupérée (doit recréer)
Le point de terminaison ne recevra plus aucune demande de Perkstar
N'affecte aucun autre webhook
Quand supprimer les webhooks :
Le point de terminaison est définitivement mis hors service
Projet d'intégration annulé
Le Webhook a été créé uniquement à des fins de test
Consolider plusieurs webhooks en un seul
Avant de supprimer :
Exporter la configuration du webhook pour la documentation
Avertir les membres de l'équipe qui peuvent s'appuyer sur le webhook
Assurez-vous qu’aucun flux de travail critique ne dépend du webhook
Pensez à désactiver d'abord pour tester l'impact avant la suppression définitive
Meilleures pratiques de sécurité
Exigences HTTPS
Avertissement: Utilisez toujours HTTPS, jamais HTTP. Les webhooks HTTP envoient des données non cryptées sur Internet. N’importe qui peut intercepter et lire les données sensibles des clients. Perkstar peut nécessiter HTTPS pour tous les webhooks.
Configuration de HTTPS :
Utilisez des fournisseurs de cloud avec HTTPS intégré (AWS, Azure, Google Cloud)
Obtenez le certificat SSL gratuit de Let's Encrypt
Utiliser des services webhook qui fournissent des points de terminaison HTTPS
Ne déployez jamais de webhooks de production sur HTTP
Vérification de la signature du webhook
Infos : Perkstar peut inclure une signature cryptographique dans les en-têtes du webhook, vous permettant de vérifier que le webhook provient bien de Perkstar et n'a pas été falsifié.
Pourquoi c'est important :
Empêche les attaquants d'envoyer de faux webhooks à votre point de terminaison
Garantit l'intégrité des données (le webhook n'a pas été modifié pendant le transport)
Nécessaire pour le traitement des actions sensibles (paiements, modifications de compte)
Comment vérifier (pseudocode) :
Consultez la documentation Perkstar :
Nom de l'en-tête de signature
Algorithme de hachage utilisé (HMAC-SHA256 typique)
Où trouver/configurer le secret du webhook
Exemple de code de vérification pour votre langue
Contrôle d'accès
Restreindre l'accès aux points de terminaison :
Utilisez des règles de pare-feu pour limiter les adresses IP pouvant accéder à votre point de terminaison webhook
Implémenter une limitation de débit (éviter les abus si URL est découvert)
Exiger des en-têtes d'authentification en plus de la vérification de la signature
Consigner toutes les demandes de webhooks pour l'audit de sécurité
N'exposez pas de données sensibles :
N'incluez pas les clés ou les mots de passe API dans les webhooks URL.
Utilisez le corps POST pour les données, pas les paramètres de requête URL
Assurez-vous que les messages d’erreur ne divulguent pas d’informations système
Désinfectez les journaux pour supprimer les données clients sensibles
Gestion des erreurs et journalisation
Journalisation complète :
Enregistrez tous les webhooks entrants avec l'horodatage et l'event_id
Enregistrez la charge utile pour le débogage (tenez compte de la confidentialité des données)
Résultats du traitement des journaux (succès, échec, erreurs)
Configurer des alertes pour les échecs répétés du webhook
Gestion gracieuse des erreurs :
Détectez et enregistrez toutes les erreurs pendant le traitement du webhook
Renvoie 200 même si la logique métier échoue (accusé de réception)
Utiliser la file d'attente de lettres mortes pour l'échec du traitement du webhook
Réessayez les opérations ayant échoué avec une interruption exponentielle
Exemple de gestion des erreurs :
Modèles de webhook avancés
Plusieurs Webhooks à des fins différentes
Vous pouvez créer plusieurs webhooks avec différentes configurations.
Exemple d'architecture :
Webhook 1 : Événements client → Synchronisations avec CRM (client.created, client.updated)
Webhook 2 : Événements de transaction → Mises à jour du système comptable (transaction.completed)
Webhook 3 : Tous les événements → Envoie à la plateforme d'analyse (tous les types d'événements)
Webhook 4 : Événements de récompense → Déclenche le workflow d'exécution (reward.issued, récompense.redeemed)
Avantages:
Séparation des préoccupations (différents systèmes gèrent différents événements)
Échec indépendant (l'échec d'un webhook n'affecte pas les autres)
Débogage et surveillance plus faciles
Sécurité/authentification différente par webhook
Modèle de diffusion
Conseil: Envoyez les webhooks à la file d’attente des messages pour distribution. Votre point de terminaison webhook reçoit les webhooks Perkstar et les publie dans la file d'attente de messages (RabbitMQ, AWS SQS, etc.). Plusieurs consommateurs traitent les événements de manière indépendante.
Avantages:
Évolutivité (plusieurs travailleurs traitent des webhooks)
Fiabilité (la file d'attente stocke les événements si les consommateurs sont en panne)
Flexibilité (ajouter de nouveaux consommateurs sans changer de webhook)
Découplage (réception du webhook séparée du traitement)
Logique de nouvelle tentative de webhook
Comprendre la livraison de webhooks :
Perkstar peut réessayer automatiquement les webhooks ayant échoué
Des tentatives se produisent si votre point de terminaison ne renvoie pas le statut 200
Délai de nouvelle tentative : généralement immédiat, 1 minute, 5 minutes, 30 minutes
Après le nombre maximal de tentatives, le webhook peut être marqué comme ayant échoué
Votre point de terminaison doit :
Renvoyez 200 rapidement (moins de 5 secondes)
Gérer les livraisons en double avec élégance (idempotence)
Ne comptez pas sur le traitement synchrone
Webhooks de file d'attente pour le traitement asynchrone
Cas d'utilisation courants
Synchronisation CRM en temps réel
But: Gardez CRM instantanément mis à jour avec l'activité du programme de fidélisation
Installation:
Abonnez-vous à : client.created, client.updated, transaction.completed
Webhook envoie des données à CRM API
Les dossiers clients restent synchronisés en temps réel
Avantages:
L'équipe commerciale voit immédiatement l'activité de fidélisation
Pas d'exportation/importation manuelle de données
Vue complète du client sur tous les systèmes
Récompense personnalisée
But: Remplissez automatiquement les récompenses en dehors de Perkstar
Installation:
Abonnez-vous à : récompense.issued, récompense.redeemed
Webhook déclenche le système d'exécution (envoyer un courriel avec le code, créer une commande d'expédition, etc.)
Confirmation renvoyée à Perkstar
Avantages:
Livraison instantanée des récompenses
Intégration avec des systèmes externes (e-cartes cadeaux, expédition des API)
Le flux de travail automatisé réduit le travail manuel
Tableaux de bord de business intelligence
But: Tableau de bord d'analyse en temps réel avec mesures de fidélité
Installation:
Abonnez-vous à : Tous les types d'événements
Webhook envoie des données à la base de données analytique
Base de données de requêtes du tableau de bord pour les métriques en direct
Avantages:
Visibilité en temps réel sur les performances du programme de fidélisation
Rapports personnalisés au-delà des analyses intégrées de Perkstar
Combinez les données de fidélité avec d’autres indicateurs commerciaux
Automatisation de l'engagement client
But: Déclenchez un communication commerciale personnalisé basé sur le comportement de fidélité Configuration de
:
Abonnez-vous à : transaction.completed, récompense.issued, retours.received
Webhook déclenche une plateforme d'automatisation du communication commerciale
Messages de suivi personnalisés envoyés automatiquement Avantages du
:
Réponse immédiate aux actions du client
L'engagement personnalisé améliore la fidélité
Le flux de travail automatisé fait gagner du temps à l'équipe communication commerciale Webhooks de dépannage
Le webhook
ne reçoit pas d'événements Problème
: vous avez créé un webhook mais aucune notification n'arrive Étapes de dépannage
:
Vérifiez que le webhook est activé :
Vérifier la colonne d'état dans la liste des webhooks
Ouvrez les détails du webhook pour confirmer que le basculement d'état est ON
Activer s'il est désactivé
Vérifiez que URL est correct :
Ouvrez les détails du webhook et vérifiez URL
Assurez-vous qu'il n'y a pas de fautes de frappe ni d'espaces supplémentaires
Confirmez qu'il s'agit du bon point de terminaison (pas localhost ou interne URL)
Tester l'accessibilité des points de terminaison :
Utilisez curl ou Postman pour envoyer une demande de test POST à votre URL
S'assurer que le point de terminaison est accessible publiquement
Vérifiez que le pare-feu ne bloque pas les requêtes des IP Perkstar
Déclenchez un événement de test :
Effectuer manuellement une action qui devrait déclencher un événement souscrit
Exemple : si vous êtes abonné à client.created, créez un client test
Vérifiez si le webhook arrive à votre point de terminaison
Examiner les abonnements aux événements :
Ouvrir les détails du webhook
Vérifiez que vous avez coché les cases des événements souhaités Le nombre d'événements
doit correspondre au nombre attendu Erreurs renvoyées par le point de terminaison
Problème
: les webhooks arrivent mais votre point de terminaison renvoie les codes d'état 4xx ou 5xx
Causes courantes et solutions :
Analyse JSON non valide :
Assurez-vous que votre code analyse correctement JSON
Poignée mal formée JSON avec élégance
Consigne la charge utile brute pour le débogage
Problèmes d'authentification/autorisation :
Si votre point de terminaison nécessite une authentification, assurez-vous que le webhook peut contourner ou dispose d'informations d'identification
Vérifier que la logique de vérification de signature est correcte
Vérifier les jetons ou certificats expirés Erreurs d'expiration du délai
:
Votre point de terminaison doit répondre dans un délai de 5 à 10 secondes
Traiter les webhooks de manière asynchrone (renvoyer 200 immédiatement, puis traiter)
Utiliser la file d'attente de messages pour les opérations de longue durée
Erreurs internes du serveur :
Vérifiez les journaux de vos applications pour connaître les détails de l'erreur.
Correction de bugs dans le code de gestion des webhooks
Ajout d'une gestion et d'une journalisation complètes des erreurs
Livraisons de webhooks en double Problème
: le même événement est diffusé plusieurs fois
Causes :
Votre point de terminaison n'a pas renvoyé 200 assez rapidement (Perkstar réessayé)
Des problèmes de réseau ont provoqué une nouvelle tentative
Il s'agit d'un comportement normal : les webhooks doivent être idempotents Solution
: implémentez l'idempotence à l'aide de event_id :
Pour le stockage persistant :
Stocker les event_ids dans la base de données
Vérifier la base de données avant le traitement
Définir TTL sur les event_ids stockés (supprimer après 30 jours) Charges utiles du Webhook
manquant de données attendues Problème
: le Webhook arrive mais ne contient pas les champs dont vous avez besoin Dépannage
:
Vérifiez la structure de la charge utile :
Enregistrez la charge utile complète pour voir ce qui est réellement envoyé
Comparer avec la structure attendue
Assurez-vous que vous recherchez le bon objet imbriqué
Vérifier le type d'événement :
Différents événements ont des structures de charge utile différentes
Assurez-vous de vous abonner à l'événement correspondant aux données dont vous avez besoin
Consultez la documentation Perkstar pour les schémas de charge utile
Gérer les champs nuls/manquants :
Tous les champs ne peuvent pas être présents dans tous les événements
Implémentez des vérifications nulles dans votre code
Utiliser les valeurs par défaut pour les champs facultatifs
Version API :
La structure de la charge utile du Webhook peut varier selon la version de API
Vérifiez si vous devez mettre à niveau ou changer de version
Contacter l'assistance pour obtenir la documentation sur les charges utiles
Résumé des meilleures pratiques
Liste de contrôle de mise en œuvre du webhook
Sécurité:
✅ Utilisez uniquement les points de terminaison HTTPS
✅ Implémenter la vérification de la signature du webhook
✅ Restreindre l'accès avec des règles de pare-feu
✅ N'exposez jamais les clés API dans les webhooks URL
✅ Enregistrez tous les webhooks pour l'audit de sécurité
Fiabilité:
✅ Renvoie immédiatement le statut 200 (moins de 5 secondes)
✅ Traitez les webhooks de manière asynchrone
✅ Implémentez l'idempotence en utilisant event_id
✅ Utilisez la file d'attente de messages pour un traitement robuste
✅ Mettre en place une surveillance et des alertes en cas de panne
Performance:
✅ Accusez réception rapidement (retour 200)
✅ File d'attente des webhooks pour le traitement en arrière-plan
✅ Échelle horizontale si le volume du webhook est élevé
✅ Utilisez la mise en cache le cas échéant
✅ Optimiser les requêtes de base de données dans les gestionnaires de webhooks
Essai:
✅ Testez avec webhook.site avant la production
✅ Créez des webhooks de test dans un environnement séparé
✅ Vérifiez que l'idempotence fonctionne correctement
✅ Testez les scénarios d'erreur et la récupération
✅ Surveillez les webhooks de test lors du déploiement initial
Entretien:
✅ Documentez tous les webhooks et leurs objectifs
✅ Consultez régulièrement les journaux des webhooks
✅ Désactivez les webhooks inutilisés pour réduire le bruit
✅ Mettre à jour les URL des points de terminaison lorsque l'infrastructure change
✅ Auditer les abonnements aux webhooks chaque trimestre
Foire aux questions
Quelle est la différence entre les webhooks et la clé API ?
La clé API vous permet d'appeler le API de Perkstar pour demander des données ou effectuer des actions. Les webhooks vous envoient automatiquement des données lorsque des événements se produisent. API = vous extrayez des données. Webhooks = Perkstar vous envoie des données.
Puis-je avoir plusieurs webhooks avec le même URL ?
Oui, mais c'est généralement inutile. Vous pouvez créer un webhook abonné à plusieurs types d'événements. Plusieurs webhooks vers le même URL peuvent entraîner des diffusions en double si les abonnements aux événements se chevauchent.
Que se passe-t-il si mon point de terminaison est en panne ?
Perkstar réessayera la livraison plusieurs fois en quelques minutes ou heures. Si toutes les tentatives échouent, le webhook peut être marqué comme ayant échoué. Vous devrez le réactiver et risquez de manquer des événements pendant les temps d'arrêt. Utilisez une file d’attente de messages pour plus de fiabilité.
Comment tester les webhooks sans affecter les données de production ?
Utilisez un compte test/sandbox Perkstar si disponible, ou créez des clients/transactions tests clairement marqués comme tests. Vous pouvez également utiliser webhook.site pour inspecter les charges utiles avant de créer votre point de terminaison.
Puis-je voir un journal des webhooks envoyés ?
Les journaux de diffusion du webhook peuvent être disponibles dans la vue détaillée du webhook, affichant les diffusions récentes, les horodatages et l'état de réussite/échec. Consultez la page de détails de chaque webhook pour connaître l’historique de livraison.
Que dois-je faire si je reçois trop de webhooks ?
Désabonnez-vous des types d'événements dont vous n'avez pas besoin ou implémentez un filtrage dans votre point de terminaison pour ignorer certains événements. Vous pouvez également traiter les webhooks par lots au lieu de les gérer individuellement.
Puis-je utiliser les URL localhost pour les tests ?
Non. Les URL locaux (les http://localhost:3000) ne sont pas accessibles au public. Utilisez ngrok, webhook.site ou déployez sur un service cloud avec un URL public à des fins de test.
Comment savoir à quels événements je dois m'abonner ?
Commencez par le nombre minimum d'événements requis pour votre cas d'utilisation. Point de départ commun : client.created et transaction.completed. Vous pourrez toujours ajouter d’autres événements ultérieurement, à mesure que les besoins évoluent.
Quelle est la taille maximale de la charge utile pour les webhooks ? Les charges utiles du Webhook
sont généralement petites (moins de 10 Ko) car elles contiennent des données d'événement concises, et non des fichiers volumineux. Si vous avez besoin d'un historique client complet, utilisez des webhooks pour déclencher des appels API qui récupèrent des données détaillées.
Les webhooks peuvent-ils envoyer des données à des points de terminaison internes (réseau privé) ?
Non. Les webhooks nécessitent des HTTPS URL accessibles au public. Pour les systèmes internes, utilisez un proxy public ou une passerelle API qui transmet les informations vers les systèmes internes en toute sécurité.
À quelle vitesse les webhooks sont-ils livrés après un événement ? Les Webhooks
sont généralement livrés quelques secondes après l'événement. Le timing exact dépend de la charge du système, mais attendez-vous à une livraison en temps quasi réel dans des conditions normales.
Que faire si je reçois un webhook pour un événement que je ne reconnais pas ?
Enregistrez la charge utile complète pour enquête. Perkstar peut ajouter de nouveaux types d'événements ou vous vous êtes peut-être abonné à des événements accidentellement. Vérifiez le champ event_type et comparez-le avec la documentation.
Puis-je filtrer les webhooks par segment de clientèle ou type de carte ? Le filtrage
n’est généralement pas disponible au niveau de l’abonnement au webhook. Vous recevrez des webhooks pour tous les événements des types abonnés et devrez filtrer votre code de point de terminaison en fonction des données de charge utile.
Comment mettre à jour mon webhook URL sans perdre la configuration ?
Modifiez le webhook existant, modifiez le URL et enregistrez. Tous les abonnements et paramètres aux événements sont conservés. Le nouveau URL reçoit immédiatement les futurs webhooks.
Les webhooks sont-ils inclus dans tous les forfaits ? La disponibilité du Webhook
dépend de votre plan d’abonnement. Vérifiez la section Plan pour voir si les webhooks sont inclus et combien vous pouvez en créer. Les forfaits de niveau supérieur offrent généralement plus de webhooks. Astuce
: Besoin d'aide supplémentaire ? Contactez l’assistance Perkstar pour le dépannage des webhooks, la documentation sur la charge utile, les conseils de mise en œuvre ou les questions techniques sur les types d’événements et leur livraison.