> 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/integration-guides/webhooks.md).

# Webhooks

Receive real-time events from The Wallet Crew with webhooks: create endpoints in the admin console or API, filter events, validate signatures, read payloads.

Webhooks let external systems receive real-time notifications when something happens in The Wallet Crew. Register an endpoint, select events, and The Wallet Crew sends a `POST` request each time one of those events occurs.

This is the simplest way to keep your CRM, analytics, or operational systems in sync without polling APIs.

<details>

<summary><strong>Real-world examples</strong></summary>

* Send a “pass installed” event to your CRM to measure adoption per campaign.
* Trigger a customer welcome journey when a customer profile is upserted.
* Log pass lifecycle events (`Pass:Created`, `Pass:Updated`) to your data warehouse.
* Track in-store QR usage by listening to redirect events (`Redirect:Redirected`).

</details>

{% hint style="info" %}
If you also enforce network restrictions, you can allowlist The Wallet Crew outgoing IPs. Do not rely on IPs only. Always validate the request signature.

See [Security and infrastructure](https://docs.thewalletcrew.io/developers-guides/pass-architecture/infrastructure.md).
{% endhint %}

## How a delivery works

The Wallet Crew checks each event against the webhook subscriptions of the tenant. For every match, it signs the JSON body and sends one `POST` request to the endpoint.

```mermaid
sequenceDiagram
    participant T as The Wallet Crew
    participant E as Your endpoint
    participant Q as Your queue
    participant S as Your systems
    T->>T: Match the event to webhook subscriptions
    T->>E: POST signed JSON body
    E->>E: Validate the signature
    E->>Q: Enqueue the event
    E-->>T: 2xx response
    Q->>S: Process the event
```

Delivery is at most once. The Wallet Crew does not retry. A non-`2xx` answer or a connection error is only logged on the platform side, so an endpoint that is down misses the events sent in the meantime.

## Create and manage a webhook

Create webhooks in the admin console, or with the REST API when registration must be automated in a deployment pipeline. A webhook defines where to send requests, which events to send, and whether delivery is active.

### Admin console

Open **Settings → General → Webhooks**. The list shows each webhook with its **Description**, **Endpoint**, **Events**, and **Enabled** status. Create a webhook, or open an existing one, to edit its form.

<div data-with-frame="true"><figure><img src="https://4179171865-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>Configure which events are delivered to which endpoint.</p></figcaption></figure></div>

| Field                     | Meaning                                                                                                                                                                           |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **ID**                    | Generated and read-only. Use it to reference the webhook through the API.                                                                                                         |
| **Secret**                | The HMAC signing key. A show/hide toggle controls its visibility. The console shows it again at any time, and the API returns it as `signatureSecret`. Store it server-side only. |
| **Active** / **Inactive** | A toggle that pauses or resumes delivery without deleting the webhook.                                                                                                            |
| **Description**           | A label for reference.                                                                                                                                                            |
| **Endpoint**              | The URL that receives the `POST` requests.                                                                                                                                        |
| **Events**                | One or more event filters. Use **Add event**, or the remove icon next to an entry, to manage the list.                                                                            |

A new webhook starts inactive, in the console and the API.

In the admin console the endpoint must be an `https://` URL. The API also accepts `http`, but use `https`. The endpoint must be reachable from the public internet: the platform refuses private-network addresses.

{% hint style="warning" %}
Treat the Secret like a password. Store it in the receiving system before you enable production processing. Never expose it in client code.
{% endhint %}

### Event filters

Each **Events** entry is a string. An entry matches an event name exactly, or as a prefix when it ends with `*`. Matching is case-sensitive. A `*` anywhere else in the entry is a literal character. At least one event is required.

| Entry          | Meaning                                    |
| -------------- | ------------------------------------------ |
| `*`            | All events.                                |
| `Pass:*`       | All events whose name starts with `Pass:`. |
| `Pass:Created` | One specific event.                        |

You can combine filters in one webhook, for example `["Customer:*", "Pass:Created"]` or `["Pass:*", "Redirect:Redirected"]`. Use wildcards carefully: you may receive more events than you need.

### REST API

The API needs the scope `tenant.webhook:read` to read webhooks and `tenant.webhook:write` to change them. Webhooks must be enabled for the tenant, otherwise the API answers `403`.

To create a webhook, send:

* `endpoint`: the URL that receives `POST` requests (`http` or `https`, `https` recommended).
* `events`: the event filters, as described above.
* `enabled`: whether delivery is active. It defaults to `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"}]}}}}}}}}}
```

The response includes the webhook `id` and `signatureSecret`. List and get operations return the secret too.

To update a webhook, use `PUT /webhooks/{id}`. It replaces the whole webhook, it does not merge: an omitted `description` is cleared and an omitted `enabled` disables the webhook. Send `enabled: true` on every update. Use `GET` to list or read webhooks and `DELETE` to remove one.

For the full API definition, use the [API reference](https://docs.thewalletcrew.io/api-reference/).

## What The Wallet Crew sends

Each delivery is an HTTP `POST` request with headers and a JSON body. The body depends on the event type.

### HTTP headers

The prefix `neostore` is the platform's former name and is kept in technical identifiers.

| Header                 | Content                                                                |
| ---------------------- | ---------------------------------------------------------------------- |
| `X-NEOSTORE-SIGNATURE` | HMAC-SHA256 signature of the JSON body.                                |
| `X-NEOSTORE-EVENTNAME` | The event that triggered the webhook, for example `Customer:Upserted`. |
| `X-NEOSTORE-TENANTID`  | The tenant identifier in The Wallet Crew.                              |

HTTP header names are case-insensitive.

### Payload envelope

Every payload includes these metadata fields:

* `__id`: the same value for every webhook subscribed to one occurrence of an event.
* `__creationDate`: the UTC time the event was raised.
* `__eventName`: the event name.

Enum values are serialized as names. Properties with a null value are omitted.

## Process events reliably

Design the receiver to be available and fast. A common pattern is to validate the signature, enqueue the event internally, then return `2xx`.

Use `__id` to ignore duplicates when the same occurrence reaches your system through more than one webhook subscription.

## Verify webhook authenticity

Validate every request using the signature header. This proves that The Wallet Crew sent the request and that the body was not modified in transit.

The signature is the HMAC-SHA256 of the UTF-8 JSON body. The key is the UTF-8 bytes of the webhook secret. The value is sent as uppercase hexadecimal, with no separator. Compute the same value over the raw body and compare it with the header, ignoring case.

```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" %}
Signature validation must use the exact raw body bytes you received. Do not re-serialize the JSON before hashing.
{% endhint %}

## Events

The event list evolves. Use the [API reference](https://docs.thewalletcrew.io/api-reference/) as the source of truth for payload shapes. These are the event names the platform raises:

| Category              | Events                                                                                                                                                                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Pass`                | `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`                                                                                                                                                                                                  |
| `Device`              | `Created`, `Deleted`, `Connected`, `SessionStarted`, `SessionEnded`                                                                                                                                                                   |
| `CustomDomain`        | `Added`, `Verified`, `Activated`, `Removed`                                                                                                                                                                                           |
| `User`                | `Created`, `Updated`, `Deleted`, `Invited`, `InvitationOpened`, `InvitationRenewed`, `Activated`, `AccessGranted`                                                                                                                     |
| `Tenant`              | `Created`, `StatusChanged`, `PurposeChanged`                                                                                                                                                                                          |
| `TenantConfiguration` | `Created`, `Updated`, `Deleted`                                                                                                                                                                                                       |
| `Customer`            | `Upserted`                                                                                                                                                                                                                            |
| `Redirect`            | `Redirected`                                                                                                                                                                                                                          |
| `Google`              | `DiscoverableProgramSignin`, `DiscoverableProgramSignup`                                                                                                                                                                              |

`TenantConfiguration` events carry the `tenantId`. `TenantConfiguration:Updated` also carries `previousVersion`, `newVersion` and `modifiedFiles`, the list of configuration files that changed.

Connector events also exist: `Y2:*`, `UR:*`, `Hiboutik:*`, `SFMC:*`, `Yurplan:*`, `Bloomreach:Customer:Upserted` and `Secutix:Order:Updated`.

<details>

<summary><strong>Customer and redirect events</strong></summary>

`Customer:Upserted` is sent when a customer is created or updated.

`Redirect:Redirected` is sent when a user opens a minified URL (redirect).

</details>

<details>

<summary><strong>Pass lifecycle events</strong></summary>

* `Pass:Installed` includes device fields.
* `Pass:ThemeChanged` is sent when a pass moves onto a different theme or has its theme removed. It carries the theme before and after the change.
* `Pass:Created` carries `creationSource`. Its `reason` holds `type`, `flowName`, `providerName` and `userId`. `creationSource` also carries tags, medium, origin and user agent. The reason `type` is one of `api`, `web`, `provider`, `customerRegistration`, `appleRecovery`, `mcp`, `benefit` or `partnerWebhook`. When the type is `api`, `userId` is the user identifier or `apiKey:{keyName}`.
* `Pass:Uninstalled` is sent each time the pass is removed from the last device of a wallet, so it is per wallet. [Wallet removal](https://docs.thewalletcrew.io/developers-guides/integration-guides/wallet/pass-lifecycle.md#wallet-removal) explains how the wallets report a removal. The payload includes:
  * `passId`, `passType`, `identifiers`, and `metadata`.
  * `device` and `deviceIdentifier`. Google does not report a device identifier, so `deviceIdentifier` is absent for Google.
  * `registrationInformation.activeRegistrationCount` and `registrationInformation.totalRegistrationCount`.

</details>

<details>

<summary><strong>Theme events</strong></summary>

`Theme:Created`, `Theme:Updated` and `Theme:Deleted` are sent when a theme is added, saved or removed. Each carries two objects:

* `theme`: `themeId`, `name` and `tags`. On `Theme:Deleted`, these describe the theme as it was before deletion; its colors and images are not included.
* `user`: who made the change, described in [Identify who made a change](#identify-who-made-a-change).

`Theme:Updated` does not say which parts of the theme changed.

`Pass:ThemeChanged` carries the pass, the theme it carries now and the theme it carried before. Either can be empty: empty before means the pass had none, empty after means the theme was removed. It is sent only when the assigned theme differs: re-saving the same theme sends no event, and creating a pass with a theme sends `Pass:Created`, not `Pass:ThemeChanged`. The same applies to admin console, automation and API changes. `Pass:Created` and `Pass:Updated` carry the theme the pass carries. Use `Pass:ThemeChanged` to measure campaign assignment without comparing pass histories.

The theme rules themselves are described in [Wallet pass themes](https://docs.thewalletcrew.io/configure/advanced-configuration/wallet/wallet-pass-themes.md).

</details>

## Identify who made a change

Configuration events name the person or API key behind a change, so that you can keep an audit trail outside The Wallet Crew. Theme, automation and benefit template events (`Theme:*`, `Automation:*`, `BenefitTemplate:*`) carry the same `user` object, with three fields:

* `credentialType`: `User` for a signed-in admin console user, `ApiKey` for an API key, `Unknown` when the change happened outside a request and carries no identity.
* `id`: the user identifier at the identity provider for a `User`, `apiKey:{name}` for an `ApiKey`. It can be empty when `credentialType` is `Unknown`. It is the same identifier the configuration history records for that change.
* `name`: a display name, when the credential carries one. For an API key, it is the name the key was issued under.

None of these objects includes an email address. The [users API](https://docs.thewalletcrew.io/api-reference/internal/access-and-security/users.md) resolves a user identifier to a person, with its email and name.

Pass events carry no `user` object. The one exception is `Pass:Created`, which names its origin in `creationSource` (see above).

## FAQ

<details>

<summary><strong>Can I read the Secret later?</strong></summary>

Yes. Open the webhook in the admin console and use the show/hide toggle, or read `signatureSecret` through the API with the scope `tenant.webhook:read`. Store the Secret server-side.

</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/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.
