The Notifications tab lets you subscribe to updates about shipments, assets, or devices. Notifications help you stay informed about important system events in real-time.

You can choose how notifications are delivered:

• Emails – Receive alerts in your inbox for quick access.
• Webhooks – Receive event data directly to a system endpoint for automated processing.

Select the method that fits your workflow or operational needs.

Accessing Notifications Menu

To access the Notifications menu:

1. Log in to the Relativity Platform.
2. In the top-right corner, select the Manage (⚙️) icon.
3. Choose Notifications from the menu to open the event types (Emails or Webhooks).

Email Notifications

The Email Notifications section shows a searchable list of system-triggered events that you can subscribe to for real-time email alerts.

Events are grouped into following two categories:

• Common Notifications
  • Asset Events
  • Device Events
  • Site Events
• Shipment Tracking
  • Shipment Events
• Cold Chain Monitoring
  • Shipment Events

Selecting an event from the list opens its subscription settings.

Common Notification Events

You can subscribe to the following types of notifications under Common Notifications. These event categories cover key activities across assets, devices, and sites.

• Asset Events: Triggered when asset-related actions occur, such as creation, provisioning, deprovisioning, dwell time, low battery, shock, tilt, or flight mode transitions.
• Device Events: Triggered by device activities, such as device return, cellular connectivity updates, or Bluetooth Low Energy (BLE) events.
• Site Events: Triggered when site-related actions occur, such as site creation, gateway provisioning, printer provisioning, or deprovisioning.

Following is a breakdown of supported events grouped into three categories:

Shipment Tracking Events

If you are using the Shipment Tracking module, you can subscribe to the following types of notifications. These events cover the full lifecycle of shipments, including creation, updates, transit milestones, and exception handling.

Cold Chain Monitoring

If you are using the Cold Chain Monitoring module, you can subscribe to the following types of notifications. These events cover the full lifecycle of shipments, including creation, updates, transit milestones, and exception handling.

Subscribing to an Event

To receive notifications for a specific event via email:

1. Navigate to: Notifications > Notification Type > Event Type > Select Event

   • Notification Type: Choose from Common Notifications, Shipment Tracking, or Cold Chain Monitoring.
   • Event Type: Expand the category (Example: Shipment Events) and select the desired event.

2. In the right-hand panel under Emails:

   • Enter Email: Enter the email address where notifications should be sent.
     • If the user already has access to the platform, their name will appear in the dropdown list. Start typing to quickly search and select them.
     • For a new user, enter the full and correct email address manually, then click Add.
   • Add: Click Add to subscribe the email to the selected event.

3. Subscribed email addresses appear in a list below, with the option to:

   • Remove (bin icon): Click the bin icon next to the email address to unsubscribe it at any time.

Enable/Disable Event Type

You can enable or disable an entire event type to control whether notifications are sent.

• Toggle the switch in the right panel to activate or deactivate event notifications according to your operational requirements.

Note: Disabling an event type prevents all subscribed users from receiving notifications for that event until re-enabled.

Best Practices

• Use distribution lists: Instead of adding multiple individual email addresses, use a group or distribution list to simplify management.
• Keep contacts updated: Regularly review and update subscribed email addresses to ensure alerts reach the correct recipients.
• Avoid personal accounts: Use official work email addresses to maintain security and ensure accountability.
• Enable only necessary events: Subscribe only to the events relevant to your operations to avoid notification fatigue.
• Test before deployment: Send test notifications to verify that emails are delivered correctly and not filtered into spam.
• Monitor critical alerts: Assign responsibility to specific team members to monitor and act on critical event notifications promptly.

Webhooks

Webhooks provide event-based (push) triggers for receiving alerts, devices, shipments, or assets data. These webhooks ensure you receive information as soon as it is processed by Tag-N-Trac, eliminating the need to repeatedly poll an API endpoint for changes.

In the Tag-N-Trac ecosystem, webhooks are associated at the account level and can be triggered by one or more system events from the data stream. This makes them ideal for integrating with external systems, automating workflows, and keeping your applications up-to-date in real time.

Webhook Configuration

When creating a webhook, you must configure the following parameters:

• URL: The endpoint where notifications will be sent. This must be a valid, accessible URL capable of handling incoming POST requests.
• Headers: (Optional) Add custom headers as key–value pairs to provide additional information or security.
  • Example:
    • Authorization: Bearer <token> (authentication)
    • Content-Type: application/json (defines payload format)

How It Works

The Webhooks feature allows you to receive real-time notifications whenever specific events occur in the platform.

• Instead of pulling updates from an API, webhooks push data directly to your configured server.
• Each webhook event delivers a JSON payload with details about what happened.
• You can subscribe to multiple events, such as asset changes, site events, or device activities.

Benefits

• Automation: Trigger downstream processes instantly when an event occurs.
• Integration: Seamlessly connect Tag-N-Trac with third-party systems.
• Efficiency: Reduce network traffic and resource usage compared to polling APIs.

Webhooks Flow Diagram

The following diagram illustrates the webhook process:

1. Platform Event: An event occurs in the platform (Example: an asset is created).
2. Webhook Service: The webhook service sends a POST request with a JSON payload to the configured Base URL.
3. External Application: The external application receives the payload and processes it (Example: updates a database, triggers an alert, or starts a workflow).

Creating a Webhook

By creating a webhook, you can configure an endpoint to automatically receive event data without needing to constantly poll the system.

To create a webhook:

1. Navigate to Notifications > Webhooks.
2. Click + Create Webhook.
3. In the Create Webhook window, provide the following information:

Webhook Information

• Base URL: Enter the URL of the server or endpoint where you want to receive webhook notifications. This must be a valid, and an accessible URL that your system can handle.

Headers

• Optionally, add Headers as key–value pairs. Headers supply metadata with each request and can be used for security, formatting, or custom data.
• Examples:
  • Content-Type: application/json → Defines the data format of the payload.
  • Authorization: Bearer <token> → Provides authentication to validate requests.
  • X-Event: payment_succeeded → Supplies a custom header with event details.

Note: The Webhook Body contains the actual event data, usually in JSON format. Headers provide additional context about the request.

Events Subscription

• Under Select events to subscribe to webhooks, choose the events you want to receive.
• You can select multiple events simultaneously.

Events are categorized as follows:

Common Events

Webhooks can be configured to notify your system about specific events that occur across assets, sites, and devices.

Each event type provides useful context for monitoring, automation, or integration with external systems.

Following is a breakdown of supported events grouped into three categories:

Module Events

Module events are triggered when specific shipment-related activities occur.

They help monitor the lifecycle of a shipment, detect exceptions, and track asset or device behavior in real-time.

Following is a breakdown of supported module events with short descriptions:

Finalizing

4. After configuring all the settings, click Create Webhook to save it.
5. To cancel, click Cancel.

   Note: Any information entered will be lost if you cancel.

Example Payload

When an event is triggered, the platform sends a JSON payload to the webhook URL.

Example Payload:

{
  "meta": {
    "solution": "track",
    "event_type": "shipment_created",
    "version": "1.0",
    "timestamp": "2025-05-23T08:33:10Z",
    "extensible_fields": []
  },
  "payload": {
    "shipment": {
      "id": "9e784932-e7ac-4845-87a8-5a74c18b0721",
      "shipment_identifier": "SHIP-TEST-001",
      "status": "ready",
      "template": {
        "id": "b31a5008-f834-48f4-98e5-54cccb7a3b6d",
        "name": "1_LEVEL_with_no_option"
      },
      "transit_start_time": "",
      "transit_end_time": "",
      "trackers": [
        {
          "device_identifier": "SSR-ST300-182",
          "primary": true
        }
      ],
      "created_at": "2025-05-23T08:32:36Z",
      "updated_at": "2025-05-23T08:33:05Z",
      "links": [],
      "extensible_fields": []
    },
    "event": {
      "id": "87d86d26-04ce-4c21-9c18-9a44cb722eed",
      "title": "Preparing",
      "message": "Shipment is getting prepared",
      "timestamp": "1747989156000",
      "unique_reading_id": "",
      "note": {},
      "extensible_fields": []
    },
    "sensor_info": {}
  }
}

Managing Webhooks

After creation, webhooks appear in the list where they can be managed.

Webhooks List

When you navigate to Notifications > Webhooks, the system displays a list of all existing webhooks.

If no webhooks exist, the system displays a message prompting you to create one.

Each entry in the list shows:

Webhook Details Page

To view the webhook details page, click on a required webhook URL from the Webhook list.

You can preview the webhook properties such as Base URL, Headers, and Event details.

Editing a Webhook

The platform provides two ways to edit a webhook: from the Webhooks List or from the Webhook Details page.

You can modify all configuration details that were provided during webhook creation, including the Base URL, Headers, and Subscribed Events.

Steps to Edit a Webhook

• From the Webhooks List:

  1. Navigate to Notifications > Webhooks.
  2. Locate the required webhook.
  3. Click the Edit button (pencil icon) in the Actions column.

• From the Webhook Details Page:

  1. Open the Webhook Details page by clicking the webhook name from the list.
  2. Click the Edit button (pencil icon) located at the top-right corner of the platform.

• After making the necessary changes, click Save Changes to update the webhook.

• Click Cancel to exit the process without applying any of the changes made.

Enabling/Disabling a Webhook

The platform provides two ways to enable or disable a webhook: from the Webhooks List or from the Webhook Details page. This allows administrators to control webhook activity based on operational needs.

Steps to Disable a Webhook

• From the Webhooks List:

  1. Navigate to Notifications > Webhooks.
  2. Locate the required webhook.
  3. Click the — Disable button in the Actions column.

• From the Webhook Details Page:

  1. Open the Webhook Details page by clicking the webhook name in the list.
  2. Click the Disable (— icon) button located at the top-right corner of the page.
  3. In the confirmation dialog:
     • Click Disable to deactivate the webhook and stop it from sending notifications.
     • Click Cancel to exit without making changes.

Steps to Enable a Webhook

• From the Webhooks List:

  1. Navigate to Notifications > Webhooks.
  2. Locate the disabled webhook.
  3. Click the Enable button in the Actions column.

• From the Webhook Details Page:

  1. Open the Webhook Details page by clicking the webhook name in the list.
  2. Click the Enable (toggle or equivalent) button at the top-right corner of the page.

Note: Once enabled, the webhook resumes sending notifications for the subscribed events.

Best Practices

• Use secure URLs: Ensure your webhook endpoint uses HTTPS to protect data in transit.
• Authenticate requests: Always use authorization headers or tokens to verify requests are from trusted sources.
• Filter events: Subscribe only to the events you need to avoid unnecessary processing.
• Monitor delivery: Ensure your endpoint responds quickly and reliably; failures may cause retries or missed events.
• Log activity: Maintain logs of incoming webhook events for troubleshooting and auditing.

Common Issues

• Using HTTP instead of HTTPS: This exposes sensitive data to potential interception.
• Not validating authenticity: Accepting requests without verifying signatures or tokens can lead to spoofed events.
• Subscribing to all events: Leads to unnecessary traffic, processing overhead, and storage issues.
• Slow or unreliable endpoints: Causes retries, delays, or even missed events if the service gives up.
• No logging or monitoring: Makes debugging difficult and reduces visibility into system behavior.