> 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 ## Webhooks Webhooks let external systems receive real-time notifications when something happens in The Wallet Crew. Register an HTTPS 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.
Real-world examples * 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`).
{% 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 `x-neostore-signature`. See [Infrastructure](/developers-guides/pass-architecture/infrastructure.md). {% endhint %} ### Create and manage a webhook Webhooks can be created and managed in two ways: from the admin console (no API required) or via the REST API. **Admin console (self-serve):** Go to **Settings → General → Webhooks**. Create or edit a webhook by filling in the **Description**, **Endpoint**, and **Events** fields. The console generates an ID and a Secret (HMAC signing key) automatically. Copy the Secret immediately after creation — it is not shown again in full. See [Webhooks (Configure)](/developers-guides/integration-guides/webhooks/webhooks-configure.md) for the full console reference. **REST API:** Use the operation below when webhook registration needs automation in a deployment pipeline. A webhook defines three things: where to send requests, which events to send, and whether the webhook is enabled. ### Create a webhook (API) When creating a webhook, send: * `endpoint`: the HTTPS URL that will receive `POST` requests. * `events`: the events you want to subscribe to. * `enabled`: whether delivery is active. You can subscribe to multiple events in one webhook. You can also use `*` to subscribe to all sub-events under a category. {% hint style="warning" %} Treat `signatureSecret` like a password. Store it securely. Use it only server-side. {% 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."}}}}}} ```` The response includes the webhook `id` and `signatureSecret`. ### Update, list, and delete You can manage webhooks using `GET`, `PATCH`, and `DELETE` on the same resource. For the full API definition, use the [API reference](https://docs.thewalletcrew.io/api-reference).
Webhook configuration screen showing event subscriptions and endpoint URL.

Configure which events are delivered to which endpoint.

### What The Wallet Crew sends Each webhook delivery is an HTTP `POST` request with headers and a JSON body. The body depends on the event type. Every payload includes the event metadata fields prefixed with `__`. ### HTTP headers * `x-neostore-signature`: HMAC SHA-256 signature of the request body, generated using your `signatureSecret`. * `x-neostore-eventname`: event name that triggered the webhook (example: `Customer:Upserted`). * `x-neostore-tenantid`: tenant identifier in The Wallet Crew. ### How to process events reliably Use `__id` as an idempotency key. If your endpoint receives the same payload twice, you can safely ignore the duplicate. Keep your handler fast. A common pattern is to validate the signature, enqueue the event internally, then return `2xx`. ### Verify webhook authenticity Validate every webhook request using `x-neostore-signature`. This ensures the request body was sent by The Wallet Crew and was not modified in transit. To validate it, compute an HMAC SHA-256 of the raw request body using your `signatureSecret`, then compare it with the header value. {% hint style="warning" %} Signature validation must use the exact raw body bytes you received. Do not re-serialize JSON before hashing. {% endhint %} ### Common events The event list evolves. Use the [API reference](https://docs.thewalletcrew.io/api-reference) as the source of truth for event names and payload shapes. Below are the most common events teams integrate with.
Customer events `Customer:Upserted` is sent when a customer is created or updated.
Pass lifecycle events Typical pass lifecycle events: * `Pass:Created` * `Pass:Installed` * `Pass:Uninstalled` * `Pass:Updated` * `Pass:UpdateSent` `Pass:Installed` includes device fields.
Redirect events `Redirect:Redirected` is sent when a user opens a minified URL (redirect).
### FAQ
Can I subscribe to all events? Yes. Use the `*` wildcard in the `events` array, for example `Customer:*`, to subscribe to all customer sub-events. Use this carefully. You may receive more events than you need.
Should my endpoint be public? Yes. The endpoint must be reachable from The Wallet Crew over HTTPS. If you restrict inbound traffic, allowlist The Wallet Crew outgoing IPs and still validate the signature.
Where do I find the exact payload schema for an event? Use the API reference. It is the source of truth for event names and payload shapes. Start with [API reference](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/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.