This documentation is currently under development. Certain sections are not yet complete and will be added shortly.
Ctrlk
HomeDocumentation
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Webhooks

Recevez des événements en temps réel de The Wallet Crew via des webhooks HTTPS. Créez des points de terminaison, validez les signatures et gérez les charges utiles d’événements courantes.

Webhooks

Les Webhooks permettent aux systèmes externes de recevoir des notifications en temps réel lorsqu’un événement se produit dans The Wallet Crew. Enregistrez un point de terminaison HTTPS, sélectionnez les événements, et The Wallet Crew envoie une POST requête chaque fois que l’un de ces événements se produit.

C’est le moyen le plus simple de garder votre CRM, vos outils d’analyse ou vos systèmes opérationnels synchronisés sans interroger les API.

Exemples concrets

  • Envoyez un événement « carte installée » à votre CRM pour mesurer l’adoption par campagne.

  • Déclenchez un parcours de bienvenue client lorsqu’un profil client est upserté.

  • Consignez les événements du cycle de vie de la carte (Carte:Created, Carte:Updated) dans votre entrepôt de données.

  • Suivez l’utilisation des QR en magasin en écoutant les événements de redirection (Redirect:Redirected).

Si vous appliquez également des restrictions réseau, vous pouvez autoriser les adresses IP sortantes de The Wallet Crew. Ne vous fiez pas uniquement aux adresses IP. Validez toujours x-neostore-signature.

Voir Infrastructure.

Créer et gérer un webhook

Les Webhooks peuvent être créés et gérés de deux façons : depuis la console d'administration (aucune API requise) ou via l’API REST.

Console d'administration (en libre-service) : Allez à Paramètres → Général → Webhooks. Créez ou modifiez un webhook en renseignant les Description, Point de terminaison, et Événements champs. La console génère automatiquement un ID et un Secret (clé de signature HMAC). Copiez le Secret immédiatement après la création — il ne sera plus affiché en entier. Voir Webhooks (Configurer) pour la documentation complète de la console.

API REST : Utilisez l’opération ci-dessous lorsque l’enregistrement des webhooks doit être automatisé dans un pipeline de déploiement. Un webhook définit trois éléments : où envoyer les requêtes, quels événements envoyer, et si le webhook est activé.

Créer un webhook (API)

Lors de la création d’un webhook, envoyez :

  • point de terminaison : l’URL HTTPS qui recevra POST les requêtes.

  • événements : les événements auxquels vous souhaitez vous abonner.

  • activé : indique si la livraison est active.

Vous pouvez vous abonner à plusieurs événements dans un seul webhook. Vous pouvez également utiliser * pour vous abonner à tous les sous-événements d’une catégorie.

Traitez signatureSecret comme un mot de passe. Stockez-le en toute sécurité. Utilisez-le uniquement côté serveur.

Create a new webhook subscription

post
/api/{tenantId}/webhooks

Registers a new webhook endpoint to receive event notifications.

Authorization

Requires Webhook.Write scope.

Automatic Generation

  • ID: 5-character random identifier (automatically assigned)

  • SignatureSecret: 64-character secret (automatically generated)

Request Signing

When sending webhook events, the platform adds an X-NEOSTORE-SIGNATURE header containing HMAC-SHA256 signature:

HMAC-SHA256(requestBody, signatureSecret)

Endpoint Requirements

  • Must accept POST requests

  • Should respond within 30 seconds

  • Should return 2xx status code for success

  • Must use HTTPS in production

Event Wildcards

  • pass.* - All pass events

  • customer.created - Specific event

  • store.*.updated - Pattern matching

Scopes requis
Cet endpoint nécessite les scopes suivants :
Autorisations
OAuth2implicitRequis
Authorization URL:
Paramètres de chemin
tenantIdstringRequis
Corps
ou
Réponses
200

OK

descriptionstring · nullableOptionnel

Description of the webhook

eventsstring[] · min: 1Requis

Events to listen. Can ends with * to listen to more than one event

endpointstring · uriRequis

Uri where a POST request will be made when the coresponding event happens.

enabledbooleanOptionnel

Determine if the webhook is enabled

Default: false
idstring · min: 1Requis

Unique identifier of this webhook

signatureSecretstring · min: 1Requis

Key used to sign the request. When The Wallet Crew platform sends a request it will add a X-NEOSTORE-SIGNATURE header with a hmacsha256 computed from the body content and this secret

post/api/{tenantId}/webhooks

La réponse inclut le webhook id et signatureSecret.

Mettre à jour, lister et supprimer

Vous pouvez gérer les webhooks à l’aide de GET, PATCH, et DELETE sur la même ressource.

Pour la définition complète de l’API, utilisez la Référence de l’API.

Webhook configuration screen showing event subscriptions and endpoint URL.
Configurez quels événements sont envoyés à quel point de terminaison.

Ce que The Wallet Crew envoie

Chaque livraison de webhook est une requête HTTP POST avec des en-têtes et un corps JSON. Le corps dépend du type d’événement. Chaque charge utile inclut les champs de métadonnées de l’événement préfixés par __.

en-têtes HTTP

  • x-neostore-signature : signature HMAC SHA-256 du corps de la requête, générée à l’aide de votre signatureSecret.

  • x-neostore-eventname : nom de l’événement qui a déclenché le webhook (exemple : Customer:Upserted).

  • x-neostore-tenantid : identifiant du tenant dans The Wallet Crew.

Comment traiter les événements de manière fiable

Utilisez __id comme clé d’idempotence. Si votre point de terminaison reçoit deux fois la même charge utile, vous pouvez ignorer sans risque le doublon.

Gardez votre gestionnaire rapide. Un schéma courant consiste à valider la signature, mettre l’événement en file d’attente en interne, puis renvoyer 2xx.

Vérifier l’authenticité du webhook

Validez chaque requête webhook à l’aide de x-neostore-signature . Cela garantit que le corps de la requête a été envoyé par The Wallet Crew et n’a pas été modifié en transit.

Pour le valider, calculez un HMAC SHA-256 du corps brut de la requête à l’aide de votre signatureSecret , puis comparez-le avec la valeur de l’en-tête.

La validation de la signature doit utiliser exactement les octets bruts du corps que vous avez reçus. Ne re-sérialisez pas le JSON avant le hachage.

Événements courants

La liste des événements évolue. Utilisez la Référence de l’API comme source de vérité pour les noms d’événements et les structures des charges utiles.

Voici les événements les plus courants avec lesquels les équipes s’intègrent.

Événements client

Customer:Upserted est envoyé lorsqu’un client est créé ou mis à jour.

Événements du cycle de vie de la carte

Événements typiques du cycle de vie de la carte :

  • Carte:Created

  • Carte:Installed

  • Carte:Uninstalled

  • Carte:Updated

  • Carte:UpdateSent

Carte:Installed inclut les champs de l’appareil.

Événements de redirection

Redirect:Redirected est envoyé lorsqu’un utilisateur ouvre une URL raccourcie (redirection).

FAQ

Puis-je m’abonner à tous les événements ?

Oui. Utilisez le * joker dans le événements tableau, par exemple Customer:*, pour vous abonner à tous les sous-événements client.

Utilisez-le avec prudence. Vous pourriez recevoir plus d’événements que nécessaire.

Mon point de terminaison doit-il être public ?

Oui. Le point de terminaison doit être accessible depuis The Wallet Crew via HTTPS.

Si vous restreignez le trafic entrant, autorisez les adresses IP sortantes de The Wallet Crew et validez tout de même la signature.

Où puis-je trouver le schéma exact de la charge utile pour un événement ?

Utilisez la référence de l’API. C’est la source de vérité pour les noms d’événements et les structures des charges utiles.

Commencez par Référence de l’API.

Mis à jour