Webhook

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

Webhooks let your systems receive real-time notifications when something happens in The Wallet Crew. You 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

You manage webhooks from the API endpoint POST /api/{tenantId}/webhooks. 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.

Example: subscribe to all customer events and to Pass:Created.

{
  "events": ["Customer:*", "Pass:Created"]
}

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

curl -X 'POST' \
  'https://app.neostore.cloud/api/{tenantId}/webhooks' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "Sync The Wallet Crew events to our CRM",
  "events": [
    "Customer:*",
    "Pass:Created"
  ],
  "endpoint": "https://your-endpoint-url.com/webhook",
  "enabled": true
}'

If creation succeeds, the API returns the webhook object, including id and signatureSecret.

{
  "id": "UniqueWebhookID",
  "signatureSecret": "GeneratedSignatureSecret",
  "description": "Sync The Wallet Crew events to our CRM",
  "events": ["Customer:*", "Pass:Created"],
  "endpoint": "https://your-endpoint-url.com/webhook",
  "enabled": true
}

Update, list, and delete

You can manage webhooks using GET, PATCH, and DELETE on the same resource.

For the full API spec, see the API reference.

Configure which events are delivered to which endpoint.

What The Wallet Crew sends (headers and payload)

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.

Example payload

{
  "passId": "ExamplePassID",
  "passType": "user",
  "identifiers": {
    "shopifyId": "ExampleShopifyID"
  },
  "metadata": null,
  "__id": "UniqueEventID",
  "__creationDate": "2025-02-17T12:27:31.6316643Z",
  "__eventName": "Pass:Created"
}

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 (signature)

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: API reference.

Below are the most common events teams integrate with.

Customer events

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

{
  "__id": "string",
  "__creationDate": "YYYY-MM-DDTHH:mm:ssZ",
  "__eventName": "Customer:Upserted",
  "flowName": "string",
  "identifiers": {},
  "attributes": {}
}

Pass lifecycle events

Typical pass lifecycle events:

• Pass:Created

• Pass:Installed

• Pass:Uninstalled

• Pass:Updated

• Pass:UpdateSent

Example: Pass:Installed includes device fields.

{
  "__id": "string",
  "__creationDate": "YYYY-MM-DDTHH:mm:ssZ",
  "__eventName": "Pass:Installed",
  "passId": "string",
  "passType": "string",
  "identifiers": {},
  "metadata": {},
  "device": "string",
  "deviceIdentifier": "string"
}

Redirect events

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

{
  "__id": "string",
  "__creationDate": "YYYY-MM-DDTHH:mm:ssZ",
  "__eventName": "Redirect:Redirected",
  "redirectId": "string",
  "newUri": "string"
}

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 here: API reference.