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 traitez 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 des événements, et The Wallet Crew envoie une POST requête chaque fois qu’un de ces événements se produit.
C’est le moyen le plus simple de synchroniser votre CRM, vos analyses ou vos systèmes opérationnels sans interroger les API en boucle.
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) : Accédez à 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 s’affiche plus en entier. Voir Webhooks (Configurer) pour la référence 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 :
endpoint: l’URL HTTPS qui recevraPOSTles requêtes.events: les événements auxquels vous souhaitez vous abonner.enabled: 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.
Creates a webhook subscription. The platform generates its identifier and signature secret.
The subscription applies from the next matching event. The response carries the generated id and signatureSecret; the Location header points to the subscription.
The caller-editable part of a webhook subscription.
Subscription created.
A webhook subscription as stored, with the values the platform generated for it.
Free text to tell subscriptions apart; not used by the platform. Omitted on an update, the current description is cleared.
Event names that trigger a delivery. An entry matches its exact event name, or every event name
starting with what precedes a trailing * (pass.*; * alone matches every event).
A * anywhere else is taken literally.
URL that receives each matching event as a JSON POST, with the headers
X-NEOSTORE-TENANTID, X-NEOSTORE-EVENTNAME and X-NEOSTORE-SIGNATURE.
Whether events are delivered. A disabled subscription is kept but receives nothing. Defaults to
false, including when omitted on an update.
falseIdentifier the platform assigns on creation. It never changes and is the id the other
webhook routes take.
Secret the platform generates on creation to sign every delivery. It never changes, not even on an update.
Body missing, events empty or missing, or endpoint missing or not an absolute http or https URL.
The caller is not authenticated.
The caller lacks the tenant.webhook:write scope, or the endpoint is not enabled for the tenant.
The tenant does not exist.
Over 1200 requests per minute to this endpoint for the tenant (default limit); retry after Retry-After.
POST /api/{tenantId}/webhooks HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 87
{
"description": null,
"events": [
"text"
],
"endpoint": "https://example.com",
"enabled": false
}{
"id": "text",
"signatureSecret": "text",
"description": null,
"events": [
"text"
],
"endpoint": "https://example.com",
"enabled": false
}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.
Ce que The Wallet Crew envoie
Chaque livraison de webhook est une POST requête HTTP 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 d’é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 votresignatureSecret.x-neostore-eventname: nom de l’événement qui a déclenché le webhook (exemple :Customer:Upserted).x-neostore-tenantid: identifiant du locataire dans The Wallet Crew.
Comment traiter les événements de manière fiable
Utilisation __id comme clé d’idempotence. Si votre point de terminaison reçoit deux fois la même charge utile, vous pouvez ignorer la duplication en toute sécurité.
Gardez votre gestionnaire rapide. Une pratique courante 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 de 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 à la valeur de l’en-tête.
Événements courants
La liste des événements évolue. Utilisez 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.
Identifier qui a effectué une modification
Les événements de configuration nomment la personne ou la clé API à l’origine d’un changement, afin qu’une piste d’audit puisse être conservée en dehors de The Wallet Crew. Les événements de carte, eux, ne le font pas : ils ne transportent aucun acteur.
Événements de thème, d’automatisation et de modèle d’avantage (Theme:*, Automation:*, BenefitTemplate:*) transportent le même user objet, avec trois champs :
credentialType—Userpour un utilisateur back-office connecté,ApiKeypour une clé API,Unknownlorsque le changement s’est produit en dehors d’une requête et ne porte aucune identité.id— l’identifiant utilisateur chez le fournisseur d’identité pour unUser,apiKey:{name}pour unApiKey. Il peut être vide lorsquecredentialTypeestUnknown. C’est le même identifiant que l’historique de configuration enregistre pour ce changement.name— un nom d’affichage, lorsque l’identifiant d’authentification en comporte un. Pour une clé API, c’est le nom sous lequel la clé a été émise.
Aucun de ces objets n’inclut d’adresse e-mail : l’ API des utilisateurs associe un identifiant utilisateur à une personne, avec son e-mail et son nom.
FAQ
Mis à jour