top of page

GET  /api/notifier/public/:project_name/subscription

​

curl -K -H "Authorization: Auth-Token YOUR_PROJECT-API-KEY" https://services.traxretail.com/api/notifier/public/my-project/subscription

Supported Protocol: HTTPS

PUT

Request Details

Request Headers

​

Authorization string

Value: 'Auth-Token {project auth token}'

Authentication token provided by Trax

​

​

Content-Type string

Value: application/json

​

​

Query Parameters

project_name string *

Project name as provided by Trax

url_list array *

list of URL you want to be notified to

wave_type_list string *

Type of waves you want to be notified on

Possible values:

'primary': Will send a notification when the session complete the main flow of Trax.

'recalculate': Will send a notification for secondary flow type of Trax. Used for data correction, usually happen in batch based Support request. 

'all': Will send a notification for the session for every kind of wave types

​

Subscription

​

DEL

Request Details

Request Headers

​

Authorization string

Value: 'Auth-Token {project auth token}'

Authentication token provided by Trax

​

​

Query Parameters

project_name string *

Project name as provided by Trax

​

Request Details

PUT  /api/notifier/public/:project_name/subscription
 

curl -K -H "Authorization: Auth-Token YOUR_PROJECT-API-KEY" "Content-Type: application/json" 
PUT "https://services.traxretail.com/api/notifier/public/my-project/subscription"
data-raw

{

  "url_list": ["https://noti-fier.url1.me/list"],

  "wave_type_list": ["primary"]

} '

Response

DELETE  /api/notifier/public/:project_name/subscription

​

curl -g DELETE "Authorization: Auth-Token YOUR_PROJECT-API-KEY" https://services.traxretail.com/api/notifier/public/my-project/subscription

 {

  "statusCode": 404,

  "message": "Not Found"

 }
-> No Configuration

​

Status Code: 200 OK
 {

  "last_update_time": "2023-02-16T15:03:17.508Z",

  "user_name": ":project-api-user",

  "url_list": [

     "https://noti-fier.url1.me/list",
     "https://noti-fier.url2.me/list" 

   ],

  "wave_type_list": [

    "primary"

   ]

 }

Status Code: 200 OK

-> Subscription done​

​

​

Status Code: 400 Bad Request

 {

  "statusCode": 400,

  "message": [

  "url_list should not be empty",

  "url_list must be an array",

  "wave_type_list should not be empty",

  "each value in wave_type_list must be a valid enum value",

  "wave_type_list must be an array"

 ],

  "error": "Bad Request"

 }

​

​

​

​

​

​

​

Response

Mandatory fields marked indicated by

Response

*

GET

Notifier

1. Overview

The Notifier service enables Trax to send event-driven HTTP callbacks (webhooks) to a client-defined endpoint.

It is primarily used to notify external systems when Analysis Results JSON results are available (online & offline SLA).

Each notification is delivered as an HTTP POST request containing a JSON payload.

2. Callback URL Configuration

The callback URL is the endpoint that will receive notifications.

Example

Requirements

  • Must be a publicly accessible HTTPS endpoint

  • Must accept HTTP POST requests

  • Must return a 2xx response to acknowledge receipt

Authentication via Query Parameter (Supported)

You can include an API key directly in the callback URL:

Notes:

  • The query parameter name (e.g., api_key) must match your configuration

  • This is the only authentication method supported via Subscription API

  • Recommended for standard integrations

3. Authentication

The Notifier service supports two authentication mechanisms depending on configuration.

3.1 Query Parameter Authentication (Default)

The API key is included in the callback URL:

  • Supported via Subscription API

  • Simple to implement

  • Default method

3.2 Header-Based Authentication (Trax Professional Only)

The API key is sent in an HTTP header:

https://client-system.com/callback?api_key=12345

Header Key: X-API-Key
Header Value: 12345

Header Key: X-API-Key
Header Value: 12345

Notes:

  • Header name is configurable (e.g., X-API-Key, Authorization)

  • Only available via Trax Professional service setup

  • Not configurable via Subscription API

  • More secure (credentials not exposed in URL)

4. Notification Payload

4.1 Standard Payload Structure

Notifications are sent as HTTP POST requests with a JSON payload.

Header Key: X-API-Key
Header Value: 12345

{
 "analysis_result_url": https://services.traxretail.com/crypt/traxus/eJfWu%2FhxyFwCLSB4HfXcbXe92HIjm2myweYDjpGDCNiEWUFVPix",
 "session_uid": "956b22ad-1819-4289-9e2e-6096d8e52223",
 "source": "Trax Retail"
}

analysis_result_url string 

URL to the Analysis Result JSON file 

​

session_uid string 

UID of the session that the Analysis Result file was generated for

​

source string 

Who created the Notification - always "Trax Retail"

Field Definitions

4.2 Additional Fields (Trax Professional Only)

For customers using that requires more information in the payload. It's possible to setup, additional metadata. This need to be requested to the Trax Professional Service team

  • store_number

  • client_session_id

{

 "analysis_result_url":"https://services.traxretail.com/crypt/traxus/eJfB4Sf7ArhJwM4PjbZxn4U%2FJjm2myweYDjpGDCNiEWUFVPix",

 "session_uid": "956b22ad-1819-4289-9e2e-6096d8e52223",

 "source": "Trax Retail",

 "store_number": "1234",

 "client_session_id": "abcde-56789"

}

Extended Example:

Notes:

  • Must be enabled during setup

  • Not available via Subscription API

  • Should be treated as optional fields

5. Subscription API

The Subscription API allows you to register your callback.

5.1 Retrieve existing subscription

{

  "statusCode": 404,

  "message": "Not Found"

 }
-> No Configuration

 

Status Code: 200 OK
 {

  "last_update_time": "2023-02-16T15:03:17.508Z",

  "user_name": ":project-api-user",

  "url_list": [

     "https://noti-fier.url1.me/list",
     "https://noti-fier.url2.me/list"

   ],

  "wave_type_list": [

    "primary"

   ]

 }

GET /api/notifier/public/:project_name/subscriptions

Field Definitions

5.2  Configure a callback URL

Authorization: Auth-Token YOUR_PROJECT-API-KEY
Content-Type: application/json

PUT "https://services.traxretail.com/api/notifier/public/my-project/subscription"
 

{

  "url_list": ["https://client-system.com/callback?api_key=12345"],

  "wave_type_list": ["primary"]

}

PUT /api/notifier/public/:project_name/subscriptions

Field Definitions

Request Headers

​

Authorization string

Value: 'Auth-Token {project auth token}'

Authentication token provided by Trax

​

​

Content-Type string

Value: application/json

​

​

Query Parameters

project_name string *

Project name as provided by Trax

url_list array *

list of URL you want to be notified to

wave_type_list string *

Type of waves you want to be notified on

Possible values:

'primary': Will send a notification when the session complete the main flow of Trax.

'recalculate': Will send a notification for secondary flow type of Trax. Used for data correction, usually happen in batch based Support request. 

'all': Will send a notification for the session for every kind of wave types

Response

Status Code: 200 OK

-> Subscription done​

​

​

Status Code: 400 Bad Request

 {

  "statusCode": 400,

  "message": [

  "url_list should not be empty",

  "url_list must be an array",

  "wave_type_list should not be empty",

  "each value in wave_type_list must be a valid enum value",

  "wave_type_list must be an array"

 ],

  "error": "Bad Request"

 }

​

​

​

​

​

​

​

5.3 Delete configuration

DELETE /api/notifier/public/:project_name/subscription

Authorization: Auth-Token YOUR_PROJECT-API-KEY

DELETE "https://services.traxretail.com/api/notifier/public/my-project/subscription"

Request Headers

​

Authorization string

Value: 'Auth-Token {project auth token}'

Authentication token provided by Trax

​

​

Query Parameters

project_name string *

Project name as provided by Trax

​

5.4 Wave types

Trax can add wave type in the factory in the future. It’s possible to control the current list of available wave type of a project

GET/api/notifier/public/wave_types

Authorization: Auth-Token YOUR_PROJECT-API-KEY

GET https://services.traxretail.com/ api/notifier/public/wave_types

Field Definitions

Request Headers

​

Authorization string

Value: 'Auth-Token {project auth token}'

Authentication token provided by Trax

​

​

Response

Status Code: 200 OK


[

  "all",

  "primary",

  "recalculate"

 ]

Important Limitations

  • Only query parameter authentication is supported via API

  • Header authentication is not supported via API

  • Header authentication requires Trax Professional setup

6. Delivery Behavior

HTTP Request Details

  • Method: POST

  • Content-Type: application/json

Expected Response

  • 2xx → success

  • Non-2xx → retried

6.1 Retry Policy

The Notifier service uses a two-level retry mechanism.

Immediate Retries

  • Up to 10 consecutive retry attempts

  • Occur within ~1 minute

Queue-Based Retries

  • If still failing, event is returned to queue

  • When processed again, up to 10 additional attempts are made

Key Implications

  • Total attempts may exceed 10

  • Retry timing depends on queue state

  • Delivery is at least once (duplicates possible)

bottom of page