> 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
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 des événements, et The Wallet Crew envoie un `POST` requête chaque fois que l’un de ces événements se produit.
C’est le moyen le plus simple de maintenir votre CRM, vos outils d’analyse ou vos systèmes opérationnels synchronisés sans interroger les API en boucle.
Exemples concrets
* Envoyez un événement « carte installée » à votre CRM pour mesurer l’adoption par campagne.
* Déclenchez un parcours d’accueil client lorsqu’un profil client est upserté.
* Journalisez 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 IP sortantes de The Wallet Crew. Ne vous fiez pas uniquement aux 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) :** 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 sera plus affiché en entier. Voir [Webhooks (Configurer)](/developers-guides/fr/integration-guides/webhooks/webhooks-configure.md) pour la référence complète de la console.
**API REST :** Utilisez l’opération ci-dessous lorsque l’enregistrement d’un webhook doit être automatisé dans un pipeline de déploiement. Un webhook définit trois choses : 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 recevra `POST` les requêtes.
* `events`: les événements auxquels vous souhaitez vous abonner.
* `enabled`: si la livraison est active.
Vous pouvez vous abonner à plusieurs événements dans un seul webhook. Vous pouvez aussi 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 lieu sûr. Utilisez-le uniquement côté serveur.
{% endhint %}
## Create a new webhook subscription
> Registers a new webhook endpoint to receive event notifications.\
> \
> \## 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":["tenant.webhook:write"]},{"apiKey":[]}],"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## 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/).
Configurez quels événements sont livré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 locataire 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 le doublon en toute sécurité.
Gardez votre gestionnaire rapide. Une approche courante consiste à valider la signature, mettre l’événement en file d’attente en interne, puis retourner `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 bien é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.
{% hint style="warning" %}
La validation de la signature doit utiliser exactement les octets bruts du corps 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 `events` tableau, par exemple `Customer:*`, pour vous abonner à tous les sous-événements client.
Utilisez-le avec précaution. 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 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.
