Webhooks

Receive real-time events from The Wallet Crew via HTTPS webhooks. Create endpoints, validate signatures, and handle common event payloads.

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

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.

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

Treat signatureSecret like a password. Store it securely. Use it only server-side.

Create a new webhook subscription

post

/api/{tenantId}/webhooks

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

Required scopes

This endpoint requires the following scopes:

Authorizations

OAuth2implicitRequired

Authorization URL:

Path parameters

tenantIdstringRequired

Body

or

Responses

200

OK

descriptionstring · nullableOptional

Description of the webhook

eventsstring[] · min: 1Required

Events to listen. Can ends with * to listen to more than one event

endpointstring · uriRequired

Uri where a POST request will be made when the coresponding event happens.

enabledbooleanOptional

Determine if the webhook is enabled

Default: false

idstring · min: 1Required

Unique identifier of this webhook

signatureSecretstring · min: 1Required

Key used to sign the request. When 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

201

Webhook created.

400

Invalid webhook payload.

401

Caller not authenticated.

403

Caller lacks Webhook.Write scope.

500

Unexpected server error.

post/api/{tenantId}/webhooks

POST /api/{tenantId}/webhooks HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 87

{
  "description": null,
  "events": [
    "text"
  ],
  "endpoint": "https://example.com",
  "enabled": false
}

{
  "id": "text",
  "signatureSecret": "text",
  "description": null,
  "events": [
    "text"
  ],
  "endpoint": "https://example.com",
  "enabled": false
}

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.

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.

Signature validation must use the exact raw body bytes you received. Do not re-serialize JSON before hashing.

Common events

The event list evolves. Use the 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.