Skip to main content
Les Pulses sont des notifications webhook qui vous permettent de recevoir des requêtes HTTP POST en temps réel lorsque des événements spécifiques se produisent dans votre boutique Chariow. Au lieu d’interroger constamment l’API, les Pulses envoient les données d’événements vers votre URL de point de terminaison configurée dès que quelque chose se produit, vous permettant de construire des intégrations et des automatisations réactives.

Comment fonctionnent les Pulses

1

Un événement se produit

Un événement se produit dans votre boutique (par exemple, une vente est finalisée).
2

Pulse déclenché

Chariow envoie une requête HTTP POST signée vers votre point de terminaison configuré.
3

Vérifier la signature

Votre serveur contrôle l’en-tête x-chariow-signature avant de faire confiance à la charge utile.
4

Traiter l'événement

Votre serveur déduplique sur x-pulse-delivery-id puis traite la charge utile.
5

Confirmer la réception

Votre serveur renvoie un code de statut 2xx pour confirmer la réception.
L’URL de votre point de terminaison est publique : quiconque la découvre peut y poster. Vérifiez toujours la signature avant d’agir sur une charge utile — voir Sécurité des Pulses.

En-têtes de la requête

Chaque livraison porte ces en-têtes :
Contrat de signature complet, extraits de vérification et diagnostic : Sécurité des Pulses.

Configuration des Pulses

Vous pouvez configurer les Pulses de plusieurs manières :

Via le tableau de bord de la boutique

  1. Allez dans AutomatisationPulses
  2. Cliquez sur Ajouter un Pulse
  3. Entrez l’URL de votre point de terminaison webhook (doit être en HTTPS)
  4. Sélectionnez les événements que vous souhaitez recevoir
  5. Sélectionnez éventuellement des produits spécifiques (laissez vide pour tous les produits)
  6. Enregistrez votre Pulse
Votre point de terminaison Pulse doit être accessible via HTTPS. Les points de terminaison HTTP ne sont pas pris en charge pour des raisons de sécurité.

Événements Pulse

Les Pulses prennent en charge les événements suivants. Lorsqu’un événement se produit, la charge utile du webhook contient un champ event avec la valeur de l’événement.

Événements de vente

Événements de licence

Événements d’affiliation

Vous pouvez configurer plusieurs événements pour une seule URL de Pulse. Lorsque l’un des événements sélectionnés se produit, Chariow enverra une notification webhook à votre point de terminaison avec la valeur d’événement correspondante.

Charge utile Pulse

Lorsqu’un événement configuré se produit, Chariow envoie une requête HTTP POST vers votre URL webhook avec les données de l’événement dans le corps de la requête. La structure exacte de la charge utile dépend du type d’événement.
Les charges utiles Pulse contiennent des données d’événement complètes, y compris des détails sur l’entité (vente, licence, etc.), les informations client, les détails du produit et le contexte de la boutique. La structure de la charge utile varie selon le type d’événement pour fournir des informations pertinentes pour chaque événement.

Exemple de vente réussie

Lorsqu’une vente est finalisée, Chariow envoie un webhook avec l’événement successful.sale :

Exemple de licence activée

Lorsqu’une licence est activée, Chariow envoie un webhook avec l’événement license.activated :

Exemple de licence bientôt expirée

Chariow analyse les licences chaque jour et envoie l’événement license.nearing_expiry une seule fois par licence, dès qu’elle entre dans la fenêtre de sept jours précédant sa date expires_at. Utilise-le pour proposer un renouvellement avant que le client ne perde son accès.
days_until_expiry n’est présent que sur cet événement. La valeur est arrondie à l’entier supérieur : une licence qui expire dans quelques heures renvoie 1. Une licence n’est annoncée qu’une seule fois, même si l’analyse est relancée avant son expiration.

Exemple d’affilié rejoint

Lorsqu’un nouvel affilié rejoint votre boutique, Chariow envoie un webhook avec l’événement affiliate.joined :
La structure exacte de la charge utile peut inclure des champs supplémentaires selon le type d’événement et le contexte. Vérifiez toujours la charge utile réelle reçue à votre point de terminaison pour la structure complète des données.

Gestion des Pulses

Exemple basique (Node.js/Express)

Exemple PHP

Politique de réessai

Si votre point de terminaison ne répond pas avec un code de statut 2xx, Chariow réessaie la livraison. Une livraison bénéficie de 5 tentatives au total, espacées par une temporisation exponentielle : Chaque tentative expire au bout de 30 secondes. La signature est calculée une seule fois à l’émission et réutilisée à l’identique par chaque réessai : une tentative qui arrive plusieurs heures plus tard reste donc vérifiable.
Après la 5e tentative infructueuse sur une même livraison, le Pulse est désactivé automatiquement et le propriétaire de la boutique, les administrateurs et les membres marketing reçoivent un courriel. Vous devez le réactiver depuis le tableau de bord avant qu’il ne se déclenche à nouveau — et avant de pouvoir rejouer ses livraisons.
Assurez-vous que votre point de terminaison Pulse répond rapidement (dans les 30 secondes). Les processus de longue durée doivent être gérés de manière asynchrone.

Historique de livraison et rejeu

Chaque tentative est enregistrée : vous pouvez donc savoir si Chariow a réellement appelé votre point de terminaison et ce qu’il a répondu. Ouvrez Automatisations → Pulses → sélectionnez votre Pulse → onglet Livraisons. Le tableau liste chaque livraison avec :
pending signifie en file d’attente ou en cours de réessai, pas en échec. Une livraison ne devient failed qu’une fois les 5 tentatives épuisées.
Un clic sur une ligne affiche la charge utile envoyée, la réponse et l’identifiant de livraison. Rejouer renvoie une charge utile stockée vers le même point de terminaison, sans retraiter la vente ou l’événement de licence d’origine — utile si votre point de terminaison était indisponible, ou pendant la mise au point de votre vérification de signature.
Un rejeu est une nouvelle livraison, avec un nouveau x-pulse-delivery-id : il passe donc votre contrôle d’idempotence et sera traité à nouveau. C’est intentionnel.

Meilleures pratiques

Renvoyez une réponse 200 immédiatement, puis traitez le Pulse de manière asynchrone pour éviter les délais d’expiration :
En raison de la logique de réessai, une même livraison peut vous parvenir plusieurs fois. Dédupliquez sur l’en-tête x-pulse-delivery-id, stable sur toutes les tentatives d’une livraison :
Ne dédupliquez pas sur l’identifiant de l’entité contenue dans la charge utile : une même vente produit légitimement une livraison par Pulse abonné.
N’agissez jamais sur une charge utile avant d’avoir contrôlé x-chariow-signature. Voir Sécurité des Pulses pour le contrat complet et des extraits prêts à l’emploi.
Utilisez toujours HTTPS pour votre point de terminaison Pulse afin de garantir que les données sont chiffrées en transit. Chariow rejettera les points de terminaison HTTP pour des raisons de sécurité.
Consultez régulièrement l’onglet Livraisons de votre Pulse. Il affiche le code de statut et le corps de réponse de chaque tentative, ce qui permet de diagnostiquer un échec sans ajouter de journalisation de votre côté.
Pour les boutiques à fort volume, envisagez de créer des Pulses séparés pour différents produits afin de rendre le traitement plus efficace et organisé.

Test des Pulses

Utilisez la fonctionnalité de test de Pulse dans votre tableau de bord :
  1. Allez dans AutomatisationsPulses
  2. Cliquez sur votre Pulse
  3. Cliquez sur Envoyer un pulse de test
  4. Vérifiez que votre point de terminaison a reçu la charge utile de test
Un événement de test est signé exactement comme un événement réel, mais il ne porte pas d’en-tête x-pulse-delivery-id (aucun enregistrement de livraison n’est créé pour lui) et sa charge utile contient un champ note supplémentaire. Pour valider votre intégration contre une charge utile réelle, rejouez plutôt une livraison depuis l’onglet Livraisons.
Pour le développement local, utilisez un service comme ngrok pour exposer votre serveur local à Internet.

Gestion des Pulses via l’API

Vous pouvez gérer vos Pulses de manière programmatique en utilisant l’API publique Chariow :

Lister tous les Pulses

Obtenir un Pulse spécifique

La réponse pour un pulse unique utilise la même structure que chaque élément dans la réponse de la liste.

Filtrer les Pulses

Vous pouvez filtrer les pulses par URL ou type d’événement en utilisant le paramètre de recherche :
Pour la documentation complète de l’API, consultez les points de terminaison Lister les Pulses et Obtenir un Pulse.

Ressources associées

Sécurité des Pulses

Vérifier les signatures et dédupliquer les réessais

Référence API - Lister les Pulses

Consultez la documentation détaillée de l’API

Référence API - Obtenir un Pulse

Obtenez un pulse spécifique via l’API

Guide des ventes

En savoir plus sur les événements de vente

Guide des licences

En savoir plus sur les événements de licence

Guide des affiliés

En savoir plus sur les événements d’affiliation