Neostore Webhooks Documentation

Neostore offers a webhook system that enables you to receive real-time notifications when specific events occur within the platform. This guide provides an overview of webhooks, instructions on configuring them, details about their structure, and a comprehensive list of available events.

What Are Webhooks?

Webhooks are user-defined HTTP callbacks that facilitate real-time communication between applications. Unlike traditional APIs, which require continuous polling to check for new data, webhooks automatically send data to a specified URL when a particular event occurs. This mechanism ensures that your systems receive timely updates without the need for constant manual checks.

For example, in our system, a webhook can be set up to notify your CRM system whenever a new customer install a pass on their phone. This immediate notification allows for prompt processing and allows many scenario, enhancing operational efficiency.

Configuring Webhooks in Neostore

To set up a webhook in Neostore, utilize the /api/{tenantId}/webhooks endpoint. This endpoint allows you to define the destination URL (endpoint) that will receive POST requests containing event data and specify which events to monitor.

When creating a new webhook, you need to provide:

• Endpoint URL: The URL where Neostore will send the POST requests.
• Events: A list of events you want to subscribe to. You can monitor multiple events with a single webhook and use the * wildcard to subscribe to all sub-events under a category.

For instance, to listen to the Pass:Created event and all events related to Customer, configure the events as follows:

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

To create a new webhook, execute the following POST request:

curl -X 'POST' \
  'https://app.neostore.cloud/api/{tenantId}/webhooks' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "Description of the webhook's purpose",
  "events": [
    "Customer:*",
    "Pass:Created"
  ],
  "endpoint": "https://your-endpoint-url.com/webhook",
  "enabled": true
}'

Upon successful creation, the API responds with a 200 status code and returns the webhook details, including a unique id and a signatureSecret used for validating incoming requests:

{
  "id": "UniqueWebhookID",
  "signatureSecret": "GeneratedSignatureSecret",
  "description": "Description of the webhook's purpose",
  "events": [
    "Customer:*",
    "Pass:Created"
  ],
  "endpoint": "https://your-endpoint-url.com/webhook",
  "enabled": true
}

You can manage existing webhooks using the GET, PATCH, and DELETE HTTP methods.

Webhook Structure

When an event you’ve subscribed to occurs, Neostore sends a POST request to your configured endpoint. This request includes specific HTTP headers and a JSON payload containing event data.

HTTP Headers:

• x-neostore-signature: An HMAC SHA-256 hash of the request body, generated using your signatureSecret. This header allows you to verify the authenticity of the request.
• x-neostore-eventname: The full name of the event that triggered the webhook (e.g., Customer:Upserted).
• x-neostore-tenantid: The tenant identifier within Neostore.

Example Payload:

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

In this payload:

• __id: Unique identifier for the event.
• __creationDate: Timestamp indicating when the event occurred.
• __eventName: Name of the event.

Other properties in the payload vary depending on the event type.

List of Available Events

Neostore supports a variety of events that you can subscribe to. You will find below a list of common events. For a comprehensive and up-to-date list of all available events, please refer to our API documentation.

Customer

Customer:Upserted

Occurs when a new customer is upserted (created or updated).

Payload Structure:

{
  "__id": "string",
  "__creationDate": "YYYY-MM-DDTHH:mm:ssZ",
  "__eventName": "string",
  "flowName": "string",
  "identifiers": {
    "type": "object",
    "description": "External identifiers of the customer"
  },
  "attributes": {
    "type": "object",
    "description": "Available attributes for this customer"
  }
}

Field Descriptions:

• flowName: Name of the flow used to upsert this customer.
• identifiers: External identifiers of the customer.
• attributes: Available attributes for this customer.

Pass Events

Pass:Created

Occurs when a new pass is created.

Payload Structure:

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

Field Descriptions:

• passId: Identifier of the pass.
• passType: Type of pass created.
• identifiers: External identifiers of the pass.
• metadata: Metadata related to the pass.

Pass:Installed

Occurs when a pass is installed.

Payload Structure:

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

Field Descriptions:

• passId: Identifier of the pass.
• passType: Type of pass installed.
• identifiers: External identifiers of the pass.
• metadata: Metadata related to the pass.
• device: Name of the device where the pass is installed (Apple or Google).
• deviceIdentifier: Identifier of the device where the pass is installed.

Pass:Uninstalled

Occurs when a pass is uninstalled.

Payload Structure:

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

Field Descriptions:

• passId: Identifier of the pass.
• passType: Type of pass uninstalled.
• identifiers: External identifiers of the pass.
• metadata: Metadata related to the pass.
• device: Name of the device where the pass was uninstalled (Apple or Google).
• deviceIdentifier: Identifier of the device where the pass was uninstalled.

Pass:Updated

Occurs when a pass is updated.

Payload Structure:

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

Field Descriptions:

• passId: Identifier of the pass.
• passType: Type of pass updated.
• identifiers: External identifiers of the pass.
• metadata: Metadata related to the pass.

Pass:UpdateSent

Occurs when a pass update is sent to the provider.

Payload Structure:

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

Field Descriptions:

• passId: Identifier of the pass.
• passType: Type of pass updated.
• identifiers: External identifiers of the pass.
• metadata: Metadata related to the pass.
• device: Name of the device where the pass is installed (Apple or Google).
• deviceIdentifier: Identifier of the device where the pass is installed.

Redirect

Redirect:Redirected

Occurs when a user is redirected from a minified URL.

Payload Structure:

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

Field Descriptions:

• redirectId: Identifier of the minified URL.
• newUri: The redirect URI.

By configuring webhooks, you can ensure your systems are promptly informed of relevant activities within Neostore, enabling seamless integration and automation of your workflows.