> 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

Recevoir des événements en temps réel de The Wallet Crew avec des webhooks : créer des points de terminaison dans la console d’administration ou via l’API, filtrer les événements, valider les signatures, lire les charges utiles.

Les webhooks permettent aux systèmes externes de recevoir des notifications en temps réel lorsqu’il se passe quelque chose dans The Wallet Crew. Enregistrez un endpoint, sélectionnez des é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 synchroniser votre CRM, vos outils d’analytique ou vos systèmes opérationnels sans interroger les API.

<details>

<summary><strong>Exemples concrets</strong></summary>

* 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é.
* Enregistrez les événements du cycle de vie d’une carte (`Carte:Created`, `Carte:Updated`) vers votre entrepôt de données.
* Suivez l’utilisation du QR en magasin en écoutant les événements de redirection (`Redirect:Redirected`).

</details>

{% hint style="info" %}
Si vous appliquez aussi des restrictions réseau, vous pouvez autoriser les IP sortantes de The Wallet Crew. Ne vous fiez pas uniquement aux IP. Validez toujours la signature de la requête.

Voir [Sécurité et infrastructure](https://docs.thewalletcrew.io/developers-guides/fr/pass-architecture/infrastructure.md).
{% endhint %}

## Comment fonctionne une livraison

The Wallet Crew vérifie chaque événement par rapport aux abonnements webhook du tenant. Pour chaque correspondance, il signe le corps JSON et envoie une `POST` requête à l’endpoint.

```mermaid
sequenceDiagram
    participant T as The Wallet Crew
    participant E as Votre endpoint
    participant Q as Votre file d’attente
    participant S as Vos systèmes
    T->>T: Faire correspondre l’événement aux abonnements webhook
    T->>E: POST du corps JSON signé
    E->>E: Valider la signature
    E->>Q: Mettre l’événement en file d’attente
    E-->>T: réponse 2xx
    Q->>S: Traiter l’événement
```

La livraison est effectuée au plus une fois. The Wallet Crew ne réessaie pas. Une réponse non-`2xx` ou une erreur de connexion n’est consignée que du côté de la plateforme ; ainsi, un endpoint en panne manque les événements envoyés entre-temps.

## Créer et gérer un webhook

Créez des webhooks dans la console d’administration, ou avec l’API REST lorsque l’enregistrement doit être automatisé dans un pipeline de déploiement. Un webhook définit où envoyer les requêtes, quels événements envoyer, et si la livraison est active.

### Console d’administration

Ouvrir **Paramètres → Général → Webhooks**. La liste affiche chaque webhook avec son **Description**, **Point de terminaison**, **Événements**, et **Activé** état. Créez un webhook, ou ouvrez-en un existant, pour modifier son formulaire.

<div data-with-frame="true"><figure><img src="https://20580291-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOnaDC4sjKAx53j0QV843%2Fuploads%2Fgit-blob-b1462ff4200123fa895afe5e5646c06802879d6c%2Fwebhook-form-new-endpoint-retake.png?alt=media" alt="New webhook form with the Description, Endpoint and Events fields and the Active toggle"><figcaption><p>Configurez quels événements sont envoyés à quel endpoint.</p></figcaption></figure></div>

| Champ                    | Signification                                                                                                                                                                                                         |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **ID**                   | Généré et en lecture seule. Utilisez-le pour référencer le webhook via l’API.                                                                                                                                         |
| **Secret**               | La clé de signature HMAC. Un bouton afficher/masquer contrôle sa visibilité. La console l’affiche à nouveau à tout moment, et l’API la renvoie sous la forme `signatureSecret`. Conservez-la uniquement côté serveur. |
| **Actif** / **Inactif**  | Un bouton qui met la livraison en pause ou la reprend sans supprimer le webhook.                                                                                                                                      |
| **Description**          | Une étiquette de référence.                                                                                                                                                                                           |
| **Point de terminaison** | L’URL qui reçoit les `POST` requêtes.                                                                                                                                                                                 |
| **Événements**           | Un ou plusieurs filtres d’événements. Utilisez **Ajouter un événement**, ou l’icône de suppression à côté d’une entrée, pour gérer la liste.                                                                          |

Un nouveau webhook commence inactif, dans la console et dans l’API.

Dans la console d’administration, l’endpoint doit être une `https://` URL. L’API accepte aussi `http`, mais utilisez `https`https\://. L’endpoint doit être accessible depuis Internet public : la plateforme refuse les adresses de réseau privé.

{% hint style="warning" %}
Considérez le Secret comme un mot de passe. Stockez-le dans le système récepteur avant d’activer le traitement en production. Ne l’exposez jamais dans le code client.
{% endhint %}

### Filtres d’événements

Chaque élément **Événements** entry est une chaîne. Une entry correspond exactement à un nom d’événement, ou comme préfixe lorsqu’elle se termine par `*`. La correspondance est sensible à la casse. Un `*` \* ailleurs dans l’entrée est un caractère littéral. Au moins un événement est requis.

| Entrée          | Signification                                          |
| --------------- | ------------------------------------------------------ |
| `*`             | Tous les événements.                                   |
| `Carte:*`       | Tous les événements dont le nom commence par `Carte:`. |
| `Carte:Created` | Un événement spécifique.                               |

Vous pouvez combiner des filtres dans un seul webhook, par exemple `["Customer:*", "Carte:Created"]` ou `["Carte:*", "Redirect:Redirected"]`. Utilisez les jokers avec prudence : vous risquez de recevoir plus d’événements que nécessaire.

### API REST

L’API a besoin du scope `tenant.webhook:read` pour lire les webhooks et `tenant.webhook:write` pour les modifier. Les webhooks doivent être activés pour le tenant, sinon l’API répond `403`.

Pour créer un webhook, envoyez :

* `endpoint`: l’URL qui reçoit `POST` les requêtes (`http` ou `https`, `https` recommandé).
* `événements`: les filtres d’événements, comme décrit ci-dessus.
* `activé`: si la livraison est active. La valeur par défaut est `false`.

## Create a webhook

> Applies from the next matching event. The id and \`signatureSecret\` are generated; \`Location\` points to the subscription.

```json
{"openapi":"3.1.1","info":{"title":"The Wallet Crew internal API","version":"v1"},"tags":[{"name":"WebHook"}],"servers":[{"url":"https://api.thewalletcrew.io","description":"Production Server"},{"url":"https://api-qa.thewalletcrew.io","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":"Free text; unused by the platform. Omitted on update, it is cleared."},"events":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Event names that trigger a delivery. An entry matches an exact name, or every name starting with the text before a trailing `*` (`Pass:*`; `*` alone matches all). A `*` elsewhere is literal."},"endpoint":{"type":"string","description":"URL receiving each matching event as a JSON `POST` with headers `X-NEOSTORE-TENANTID`, `X-NEOSTORE-EVENTNAME` and `X-NEOSTORE-SIGNATURE`.","format":"uri"},"enabled":{"type":"boolean","description":"Whether events are delivered; a disabled subscription is kept but receives nothing. Default `false`, also when omitted on update.","default":false}},"additionalProperties":false,"description":"The editable part of a webhook subscription."},"WebHookWithId":{"required":["id","signatureSecret"],"type":"object","allOf":[{"description":"The editable part of a webhook subscription.","$ref":"#/components/schemas/WebHook"}],"properties":{"id":{"minLength":1,"type":"string","description":"Id assigned on creation; immutable; the `id` of the other webhook routes."},"signatureSecret":{"minLength":1,"type":"string","description":"Secret generated on creation, used to sign deliveries; never changes. Keep it server-side."}},"additionalProperties":false,"description":"A stored webhook subscription, with generated values."},"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 webhook","description":"Applies from the next matching event. The id and `signatureSecret` are generated; `Location` points to the subscription.","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Events, endpoint and enabled flag.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WebHook"},{"$ref":"#/components/schemas/WebHookWithId"}],"description":"The editable part of a webhook subscription."}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WebHook"},{"$ref":"#/components/schemas/WebHookWithId"}],"description":"The editable part of a webhook subscription."}},"application/*+json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WebHook"},{"$ref":"#/components/schemas/WebHookWithId"}],"description":"The editable part of a webhook subscription."}}},"required":true},"responses":{"201":{"description":"Subscription created.","content":{"text/plain":{"schema":{"description":"A stored webhook subscription, with generated values.","$ref":"#/components/schemas/WebHookWithId"}},"application/json":{"schema":{"description":"A stored webhook subscription, with generated values.","$ref":"#/components/schemas/WebHookWithId"}},"text/json":{"schema":{"description":"A stored webhook subscription, with generated values.","$ref":"#/components/schemas/WebHookWithId"}}}},"400":{"description":"Body missing, `events` empty or missing, or `endpoint` missing or not an absolute `http`/`https` URL.","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":"The caller is not authenticated.","content":{"application/problem+json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"403":{"description":"The caller lacks the `tenant.webhook:write` scope, or the endpoint is not enabled for the tenant.","content":{"application/problem+json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"404":{"description":"The tenant does not exist.","content":{"application/problem+json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"429":{"description":"Over 1200 requests per minute to this endpoint for the tenant (default limit); retry after `Retry-After`.","headers":{"Retry-After":{"description":"Seconds to wait before retrying. Sent when the limiter knows it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}}}}}}}
```

La réponse inclut le webhook `id` et `signatureSecret`. Les opérations de liste et de récupération renvoient aussi le secret.

Pour mettre à jour un webhook, utilisez `PUT /webhooks/{id}`. Il remplace entièrement le webhook, il ne fusionne pas : un `description` omis est effacé et un `activé` omis désactive le webhook. Envoyez `enabled: true` à chaque mise à jour. Utilisez `GET` pour lister ou lire les webhooks et `DELETE` pour en supprimer un.

Pour la définition complète de l’API, utilisez le [référence de l'API](https://docs.thewalletcrew.io/api-reference/).

## Ce que The Wallet Crew envoie

Chaque livraison est une requête HTTP `POST` avec des en-têtes et un corps JSON. Le corps dépend du type d’événement.

### En-têtes HTTP

Le préfixe `neostore` est l'ancien nom de la plateforme et est conservé dans les identifiants techniques.

| En-tête                | Contenu                                                                  |
| ---------------------- | ------------------------------------------------------------------------ |
| `X-NEOSTORE-SIGNATURE` | Signature HMAC-SHA256 du corps JSON.                                     |
| `X-NEOSTORE-EVENTNAME` | L’événement qui a déclenché le webhook, par exemple `Customer:Upserted`. |
| `X-NEOSTORE-TENANTID`  | L’identifiant du tenant dans The Wallet Crew.                            |

Les noms des en-têtes HTTP ne sont pas sensibles à la casse.

### Enveloppe du payload

Chaque payload inclut ces champs de métadonnées :

* `__id`: la même valeur pour chaque webhook abonné à une occurrence d’un événement.
* `__creationDate`: l’heure UTC à laquelle l’événement a été émis.
* `__eventName`: le nom de l’événement.

Les valeurs d’énumération sont sérialisées sous forme de noms. Les propriétés ayant une valeur null sont omises.

## Traitez les événements de manière fiable

Concevez le récepteur pour qu’il soit disponible et rapide. Un schéma courant consiste à valider la signature, mettre l’événement en file d’attente en interne, puis à renvoyer `2xx`.

Utilisez `__id` afin d’ignorer les doublons lorsque la même occurrence atteint votre système via plusieurs abonnements webhook.

## Vérifiez l’authenticité des webhooks

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

La signature est le HMAC-SHA256 du corps JSON UTF-8. La clé est les octets UTF-8 du secret du webhook. La valeur est envoyée en hexadécimal majuscule, sans séparateur. Calculez la même valeur sur le corps brut et comparez-la à l’en-tête, en ignorant la casse.

```javascript
const crypto = require("crypto");

function isValidSignature(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex")
    .toUpperCase();
  const received = (signatureHeader || "").toUpperCase();
  return (
    expected.length === received.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))
  );
}
```

{% 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 de le hacher.
{% endhint %}

## Événements

La liste des événements évolue. Utilisez [référence de l'API](https://docs.thewalletcrew.io/api-reference/) comme source de vérité pour les formes de payload. Voici les noms d’événements émis par la plateforme :

| Catégorie             | Événements                                                                                                                                                                                                                            |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Carte`               | `Created`, `Updated`, `ThemeChanged`, `PassTypeChanged`, `IdentifiersChanged`, `MetadataChanged`, `Installed`, `Uninstalled`, `UpdateSent`, `Scanned`, `NotificationSent`, `LinkOpened`, `GoalReached`, `StampApplied`, `StampsReset` |
| `Benefit`             | `Created`, `Updated`, `Deleted`, `MovementApplied`                                                                                                                                                                                    |
| `BenefitTemplate`     | `Created`, `Updated`, `Deleted`                                                                                                                                                                                                       |
| `Theme`               | `Created`, `Updated`, `Deleted`                                                                                                                                                                                                       |
| `Automation`          | `Created`, `Updated`, `Deleted`, `Executed`                                                                                                                                                                                           |
| `Import`              | `Started`, `Completed`, `Failed`                                                                                                                                                                                                      |
| `Campaign`            | `LinkOpened`, `LinkDeliveryReported`                                                                                                                                                                                                  |
| `Appareil`            | `Created`, `Deleted`, `Connected`, `SessionStarted`, `SessionEnded`                                                                                                                                                                   |
| `CustomDomain`        | `Added`, `Verified`, `Activated`, `Removed`                                                                                                                                                                                           |
| `Utilisateur`         | `Created`, `Updated`, `Deleted`, `Invited`, `InvitationOpened`, `InvitationRenewed`, `Activated`, `AccessGranted`                                                                                                                     |
| `Tenant`              | `Created`, `StatusChanged`, `PurposeChanged`                                                                                                                                                                                          |
| `TenantConfiguration` | `Created`, `Updated`, `Deleted`                                                                                                                                                                                                       |
| `Customer`            | `Upserted`                                                                                                                                                                                                                            |
| `Redirect`            | `Redirected`                                                                                                                                                                                                                          |
| `Google`              | `DiscoverableProgramSignin`, `DiscoverableProgramSignup`                                                                                                                                                                              |

`TenantConfiguration` les événements portent `tenantId`. `TenantConfiguration:Updated` porte aussi `previousVersion`, `newVersion` et `modifiedFiles`, la liste des fichiers de configuration qui ont changé.

Des événements de connecteur existent aussi : `Y2:*`, `UR:*`, `Hiboutik:*`, `SFMC:*`, `Yurplan:*`, `Bloomreach:Customer:Upserted` et `Secutix:Order:Updated`.

<details>

<summary><strong>Événements client et de redirection</strong></summary>

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

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

</details>

<details>

<summary><strong>Événements du cycle de vie d’une carte</strong></summary>

* `Carte:Installed` inclut des champs d’appareil.
* `Carte:ThemeChanged` est envoyé lorsqu’une carte passe à un thème différent ou que son thème est supprimé. Il transporte le thème avant et après le changement.
* `Carte:Created` porte `creationSource`. Son `reason` contient `type`, `flowName`, `providerName` et `userId`. `creationSource` porte aussi les tags, le medium, l’origine et le user agent. La raison `type` fait partie de `api`, `web`, `fournisseur`, `customerRegistration`, `appleRecovery`, `mcp`, `benefit` ou `partnerWebhook`. Lorsque le type est `api`, `userId` est l’identifiant utilisateur ou `apiKey:{keyName}`.
* `Carte:Uninstalled` est envoyé chaque fois que la carte est retirée du dernier appareil d’un wallet, donc c’est par wallet. [Suppression du wallet](https://docs.thewalletcrew.io/developers-guides/fr/integration-guides/wallet/pass-lifecycle.md#wallet-removal) explique comment les wallets signalent une suppression. Le payload inclut :
  * `passId`, `passType`, `identifiers`, et `métadonnées`.
  * `appareil` et `deviceIdentifier`. Google ne signale pas d’identifiant d’appareil, donc `deviceIdentifier` est absent pour Google.
  * `registrationInformation.activeRegistrationCount` et `registrationInformation.totalRegistrationCount`.

</details>

<details>

<summary><strong>Événements de thème</strong></summary>

`Theme:Created`, `Theme:Updated` et `Theme:Deleted` sont envoyés lorsqu’un thème est ajouté, enregistré ou supprimé. Chacun porte deux objets :

* `theme`: `themeId`, `name` et `balises`. Sur `Theme:Deleted`, ceux-ci décrivent le thème tel qu’il était avant la suppression ; ses couleurs et ses images ne sont pas incluses.
* `user`: qui a effectué la modification, décrit dans [Identifier qui a effectué une modification](#identify-who-made-a-change).

`Theme:Updated` n’indique pas quelles parties du thème ont changé.

`Carte:ThemeChanged` porte la carte, le thème qu’elle porte maintenant et le thème qu’elle portait avant. L’un ou l’autre peut être vide : vide avant signifie que la carte n’en avait pas, vide après signifie que le thème a été supprimé. Il est envoyé uniquement lorsque le thème assigné diffère : réenregistrer le même thème n’envoie aucun événement, et créer une carte avec un thème envoie `Carte:Created`, et non `Carte:ThemeChanged`. La même chose s’applique aux changements de la console d’administration, de l’automatisation et de l’API. `Carte:Created` et `Carte:Updated` portent le thème que la carte porte. Utilisez `Carte:ThemeChanged` pour mesurer l’affectation d’une campagne sans comparer l’historique des cartes.

Les règles de thème elles-mêmes sont décrites dans [les thèmes des cartes Wallet](https://docs.thewalletcrew.io/configure/fr/advanced-configuration/wallet/wallet-pass-themes.md).

</details>

## Identifier qui a effectué une modification

Les événements de configuration nomment la personne ou la clé API derrière un changement, afin que vous puissiez conserver une piste d’audit en dehors de The Wallet Crew. Les événements de thème, d’automatisation et de modèle de bénéfice (`Theme:*`, `Automation:*`, `BenefitTemplate:*`) portent le même `user` objet, avec trois champs :

* `credentialType`: `Utilisateur` pour un utilisateur de la console d’administration connecté, `ApiKey` pour une clé API, `Unknown` lorsque le changement s’est produit hors requête et ne porte aucune identité.
* `id`: l’identifiant utilisateur chez le fournisseur d’identité pour un `Utilisateur`, `apiKey:{name}` pour un `ApiKey`. Il peut être vide lorsque `credentialType` est `Unknown`. C’est le même identifiant que l’historique de configuration enregistre pour ce changement.
* `name`: un nom d’affichage, lorsque l’identifiant en porte 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](https://docs.thewalletcrew.io/api-reference/internal/access-and-security/users.md) résout un identifiant utilisateur en une personne, avec son e-mail et son nom.

Les événements de carte ne portent aucun `user` objet. La seule exception est `Carte:Created`, qui indique son origine dans `creationSource` (voir ci-dessus).

## FAQ

<details>

<summary><strong>Puis-je lire le Secret plus tard ?</strong></summary>

Oui. Ouvrez le webhook dans la console d’administration et utilisez le bouton afficher/masquer, ou lisez `signatureSecret` via l’API avec le scope `tenant.webhook:read`. Stockez le Secret côté serveur.

</details>


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.thewalletcrew.io/developers-guides/fr/integration-guides/webhooks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
