> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/developers-guides/fr/integration-guides/webhooks.md). # Webhooks ## 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`).
{% hint style="info" %} 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](/developers-guides/fr/pass-architecture/infrastructure.md). {% endhint %} ### 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)](/developers-guides/fr/integration-guides/webhooks/webhooks-configure.md) 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. {% hint style="warning" %} Traitez `signatureSecret` comme un mot de passe. Stockez-le en toute sécurité. Utilisez-le uniquement côté serveur. {% endhint %} ## Create a new webhook subscription > 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 ````json {"openapi":"3.1.1","info":{"title":"Neostore internal API","version":"v1"},"tags":[{"name":"WebHook"}],"servers":[{"url":"https://app.neostore.cloud","description":"Production Server"},{"url":"https://app-qa.neostore.cloud","description":"Staging Server"}],"security":[{"admin-bearer":["ScopedAuthorizeRequirement"]},{"apiKey":["ScopedAuthorizeRequirement"]}],"components":{"securitySchemes":{"admin-bearer":{"type":"oauth2","flows":{"implicit":{"authorizationUrl":"https://auth.neostore.cloud/authorize?audience=https://app.neostore.cloud/api/","scopes":{}}}},"apiKey":{"type":"apiKey","name":"X-API-KEY","in":"header"}},"schemas":{"WebHook":{"required":["endpoint","events"],"type":"object","properties":{"description":{"type":["null","string"],"description":"Description of the webhook"},"events":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Events to listen. Can ends with * to listen to more than one event"},"endpoint":{"type":"string","description":"Uri where a POST request will be made when the coresponding event happens.","format":"uri"},"enabled":{"type":"boolean","description":"Determine if the webhook is enabled","default":false}},"additionalProperties":false},"WebHookWithId":{"required":["id","signatureSecret"],"type":"object","allOf":[{"$ref":"#/components/schemas/WebHook"}],"properties":{"id":{"minLength":1,"type":"string","description":"Unique identifier of this webhook"},"signatureSecret":{"minLength":1,"type":"string","description":"Key used to sign the request.\nWhen 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"}},"additionalProperties":false},"ProblemDetails":{"type":"object","properties":{"type":{"type":["null","string"]},"title":{"type":["null","string"]},"status":{"type":["null","integer"],"format":"int32"},"detail":{"type":["null","string"]},"instance":{"type":["null","string"]}},"additionalProperties":{}},"HttpValidationProblemDetails":{"type":"object","allOf":[{"$ref":"#/components/schemas/ProblemDetails"}],"properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"additionalProperties":{}}}},"paths":{"/api/{tenantId}/webhooks":{"post":{"tags":["WebHook"],"summary":"Create a new webhook subscription","description":"Registers a new webhook endpoint to receive event notifications.\n\n## Authorization\nRequires `Webhook.Write` scope.\n\n## Automatic Generation\n- **ID**: 5-character random identifier (automatically assigned)\n- **SignatureSecret**: 64-character secret (automatically generated)\n\n## Request Signing\nWhen sending webhook events, the platform adds an `X-NEOSTORE-SIGNATURE` header containing HMAC-SHA256 signature:\n```\nHMAC-SHA256(requestBody, signatureSecret)\n```\n\n## Endpoint Requirements\n- Must accept POST requests\n- Should respond within 30 seconds\n- Should return 2xx status code for success\n- Must use HTTPS in production\n\n## Event Wildcards\n- `pass.*` - All pass events\n- `customer.created` - Specific event\n- `store.*.updated` - Pattern matching","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"The webhook to create","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WebHook"},{"$ref":"#/components/schemas/WebHookWithId"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WebHook"},{"$ref":"#/components/schemas/WebHookWithId"}]}},"application/*+json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WebHook"},{"$ref":"#/components/schemas/WebHookWithId"}]}}},"required":true},"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/WebHookWithId"}},"application/json":{"schema":{"$ref":"#/components/schemas/WebHookWithId"}},"text/json":{"schema":{"$ref":"#/components/schemas/WebHookWithId"}}}},"201":{"description":"Webhook created."},"400":{"description":"Invalid webhook payload.","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"401":{"description":"Caller not authenticated.","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"403":{"description":"Caller lacks Webhook.Write scope.","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"500":{"description":"Unexpected server error."}}}}}} ```` 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](https://docs.thewalletcrew.io/api-reference).
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. {% hint style="warning" %} 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. {% endhint %} ### Événements courants La liste des événements évolue. Utilisez la [Référence de l’API](https://docs.thewalletcrew.io/api-reference) 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](https://docs.thewalletcrew.io/api-reference).
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.thewalletcrew.io/developers-guides/fr/integration-guides/webhooks.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.