Setting up Subscriptions

Copyright IBM Corporation and GTD Solution Inc. 2018, 2022

Note: See the Data Sharing Specification section for details on the TradeLens data sharing model. It describes the data that various participants provide to the platform, how that data is shared with others, and the data access for the participants.

Subscribing to Events

The TradeLens platform provides several types of event subscriptions:

• Organization: subscribes to all events that are determined to be associated with the organization.

• Country: subscribes to all events for a specific country. This includes all events originating, passing through, and arriving at the country.

• Port: subscribes to all events for a specific port of call. This includes all events originating, passing through, and arriving at the port.

• Province: subscribes to all events for a province. This includes all events for all consignments and transport equipment that pass through any port in a set of ports. This set is provided in the optional 'ports' field in the subscription. If the user does not specify a set of ports, then the subscription will default to all the ports for which this org has a province role.

• Terminal: subscribes to all events that pass through a specific terminal.

The role of your organization determines the subscription type(s) you can create. Organization subscriptions can be set up if you are a member of the organization. Ports and terminals can set up a subscription for a port or a terminal. Authorities can set up a subscription for a country. When your organization is provisioned to TradeLens, if the organization is authority, customs, port, or terminal for example, that enables a special privilege. Any user id associated with an organization type of authority or customs is authorized to create a country subscription for the associated country.

Port Role and Port Event types are optional fields for Port Subscriptions. Country Role and Country Event Types are also optional fields for Country Subscriptions. However, there is a required relationship between Role and Event Types:

• In port subscriptions, if you specify a Port Role then you must provide a Port Event Type.
• In country subscriptions, if you specify a Country Role then you must provide a Country Event Type.

Each organization can have a maximum of 5 subscriptions per individual type: 5 for your organization, 5 for each country, 5 for each port, 5 for each province, and 5 for each terminal. For example, if an organization is onboarded with 3 different ports and has 5 subscriptions for each port, they would have 15 port subscriptions.

Webhooks

Overview

When you create a subscription, you supply a webhook, the URL of where the TradeLens platform should publish the events for that subscription. The URL must specify HTTPS. The webhook will receive arrays of events as the body of an HTTP POST request. The webhook must respond with an HTTP success code response (2nn) within 5 seconds or the connection will be timed out. If the connection is timed out, TradeLens will save the payload and try again later. Unpublished payloads will be kept for 7 days. Anything older than that will be deleted. If your service requires more than 5 seconds to process some events, it is recommended that the webhook responds to the HTTPS request with a success code to confirm it has received the event before it completes processing of the event.

If you are creating a port, province, country, or terminal subscription, you can only use a port (or ports for a province), country, or terminal that your organization was associated with during the provisioning process. For an organization type subscription, you do not need to specify your organization since TradeLens knows the organization associated with your user ID.

Each event published to the webhook will contain all information from the original publisher. Additional fields will be added for the convenience of associating events with associated shipments, consignments, and transport equipment. For example:

• If the event is on the level of a transport equipment, both the "transportEquipmentId" and "equipmentNumber" will be added to the event if they were not originally present. If the transport equipment was associated with any consignments at the time the event was sent to the webhook, then the "associatedConsignmentIds" field will be populated with the consignmentId of all those consignments.
• If the event was published to a consignment, the "consignmentId" associated with the consignment will be added to the event.
• All events are given an internal "type" field corresponding to the code of their type (for example "E025").

Below is a sample payload that will be posted to your webhook. In this case it is an array of a single event.

[
    {
        "eventSubmissionTime": 1523633968187,
        "type": "E021",
        "originatorId": "origninatorId",
        "eventOccurrenceTime": 1523633968187,
        "originatorName": "originatorName",
        "transportEquipmentId": "6c995b93-ddf8-4062-a519-99db31a111ef",
        "equipmentNumber": "anEquipmentNumber",
        "transportationPhase": "Transshipment",
        "associatedConsignmentIds": ["ConsignmentId1", "ConsignmentId2"],
        "location": {
           "type": "UN/Locode",
           "value": "NLRTM"
        }
    }
]

Filtering by Event Type

By default, events of all types will be sent to a subscription. You can filter this list down to a subset of event types for organization, country, port, and province subscriptions (no support for terminal at this time). When configuring the filter, you select the event types that you want to be included. All others will be excluded. The list of valid event types can be found in the GET ../eventTypes - Get all event types API in the Platform Constants API section of the Swagger. The array field in the subscription configuration is orgEventTypes, countryEventTypes, portEventTypes, or provinceEventTypes depending on the type of subscription being configured. The values in the array can be the full names of the events (for example "plannedVesselArrival") or the Exxx code (for example "E310") where applicable.

If interested in document events, you can choose the event type documentEvents. In addition, you might want to filter the event list even further to a subset of the document types reported or the applicable action represented by the event. This can be set up in the docEventFilters portion of the configuration. It is an array of action and document type pairs. The list of valid document types and actions can be found in the GET .../documentTypes - Returns docTypes used to validate content and GET .../documentActions - Get all Document actions APIs in the Platform Constants API section of the Swagger. If action is not specified, then document events whose document type matches the filter, regardless of their associated action, will be sent to the subscription. To allow all document events to be sent to the subscription, just add documentEvents to the associated event types array and do not specify docEventFilters.

The following examples are for an organization subscription. Replace "org" in "orgEventTypes" with applicable values for other subscriptions types.

To subscribe to all document events:

"orgEventTypes": [
    "documentEvents"
]

To subscribe to PRO_FORMA_INVOICE submitted document events:

"orgEventTypes": [
    "documentEvents"
],
"docEventFilters": [
    {
        "action": "submitted",
        "docType": "PRO_FORMA_INVOICE"
    }
]

To subscribe to plannedVesselArrival and SHIPPING_INSTRUCTIONS submitted events:

"orgEventTypes": [
    "plannedVesselArrival"
],
"docEventFilters": [
    {
        "action": "submitted",
        "docType": "SHIPPING_INSTRUCTIONS"
    }
]

Protocol Requirements

As noted above, your webhook URL must specify HTTPS. More specifically, it must support TLS 1.2. As an HTTPS / TLS server, your webhook server must present X.509 certificate information during the initial TLS security handshake. Your server's certificate must be signed by a well-known certificate authority (CA), perhaps through a certificate chain that includes one or more intermediate certificates, but it cannot be a self-signed certificate. Also, as required by the TLS specification, your server must submit the entire certificate chain during the TLS handshake, including its own certificate, any intermediate certificates that your server may employ, and finally a root certificate that belongs to the list of well-known CA's.

Security using a Shared Secret

For additional security, a webhook can optionally be configured with a shared secret, a key used to hash the event contents and store the results in the X-GTD-Signature header to be provided when publishing to your webhook. In your webhook application, you should use your shared secret to hash the event contents and ensure the resulting hash value matches what is found in the header. This allows you to verify the sender.

Guidelines for the shared secret:

• Your shared secret should be sufficiently long to be cryptographically secure.

• You should not use a predictable secret, like “passw0rd” or “sharedsecret1” since these can be easily brute forced.

• It is recommended that you use a 30+ character string, created using a cryptographically secure random number generator.

• You should not use the same shared secret across multiple subscriptions.

• You should not store your webhook secret in “clear text” (unencrypted) anywhere in your system. You should store your secret in an encrypted format to prevent attackers from accessing your shared secrets.

• If your subscription is long lived (you expect to continue receiving events for it over a period of months, this will usually be true for port, country, and org level subscriptions) you should change your shared secret regularly (at least once every 3 months).

See the API User Guide section for the Swagger URLs and the Event Subscription API Swagger for more details.

Security using OAuth2

Another option for enhanced security is using an OAuth2 enabled webhook application. OAuth2 is a well known standard designed to allow a website or application to access resources hosted by other web apps on behalf of a user. Similar to the shared secret option, OAuth2 allows your webhook application to verify the sender of the events (TradeLens). However, this kind of access requires tokens that represent delegated right of access.

Configuring your subscription's webhook to leverage OAuth2 involves assigning the following fields:

• accessTokenUri: Required. This is the URI used to fetch an identity token, where the data fields below will be provided.

• clientId: Required. Public identifier for the calling application.

• clientSecret: Required. Private identifier known only by the server.

• grantType: Optional. Only client_credentials is a valid value at this time.

• scope: Optional. Clarifies the scope of the resulting token, how it can be used. Default value "read".

Below is an example subscription configuration leveraging OAuth2.

"webhookOAuth2": {
    "accessTokenUri": "https://mywebhook.com/cUhsoSv2vsarYJFm",
    "clientCredentials": {
        "clientId": "1234",
        "clientSecret": "********"
    },
   "grantType": "client_credentials",
   "scope": "read"
}

Subscription Event Schema

To assist in consuming the payload sent to your webhook from the subscription service, TradeLens provides the JSON schema in the GET ​...​/subscriptions​/event​/schema - Get subscription event schema API, that can be found in the Event Subscription API section of the Swagger. The API is for documentation purposes only. You can read the Swagger documentation and open the Model in the Responses section of the Swagger to see the superset of fields possible in events that are posted to configured event subscriptions. Descriptions are also provided for each field. Note that subscription data consists of data from the event payload as provided by the publisher, plus additional data from TradeLens to assist the subscribers. When creating a new subscription from the UI, you will notice a link to Schema (shown in the example screen images below). The schema can also be found at the following links in the Event Subscription API Swagger.

Note: If you have been onboarded onto a different stack than "platform", replace "platform" with your stack name, for example "maersk", in the URLs below.

Sandbox Subscription Event Schema:
https://platform-sandbox.tradelens.com/documentation/swagger/?urls.primaryName=Event%20Subscription%20API

Production Subscription Event Schema:
https://platform.tradelens.com/documentation/swagger/?urls.primaryName=Event%20Subscription%20API

Example Organization Subscription

The example below shows how you can create an Organization subscription using the UI (see section Create a Subscription using the UI), or through the Swagger APIs (see section Create a Subscription using the Swagger APIs). It also demonstrates how you can test the subscription (see section Test a Subscription).

Create a Subscription using the UI

1. Go to the Shipment Manager UI and log in.

2. Click on Account, then click Subscriptions.

3. Click Create New Subscription.
   

4. As discussed earlier, depending on the role of your organization, you will see different choices for the types of subscriptions that you can create (organization, country, port, province, terminal). For our example we will select Organization Subscription.
   

5. Enter a Name (optional) and the URI for your webhook. The URI must specify HTTPS. For our simplified example, we are going to use a test webhook. In a real scenario, you must have your own code ready to receive data at your webhook URI. If you click within the Organization Event Types (optional) field, you can select the type of events for the subscription. In our example, we want all events for our organization so we will not add specific events.

   The Subscription Security (optional) allows you to select either Shared Secret or OAuth2. If you select one of the options, you will see additional fields that you can enter for your subscription. Shared Secret and OAuth2 are described in the earlier sections. More details are provided in Swagger and can also be found by clicking on the Implementation Notes text on the UI.

6. Click Create.
   

If you want to create a subscription using the Swagger APIs, see the next section. Otherwise, skip to the Test a Subscription section.

Create a Subscription using the Swagger APIs

Use the following steps to start Port, Terminal, Country, and Organization subscriptions. Note that this process can be done through your client code by calling the Platform Subscription APIs directly, see the API User Guide section for the Swagger URLs. The process below describes how you would do this from the Swagger until you are ready to write (or integrate) your client code for a system user.

1. Select the Event Subscription API in the top right area Select a definition. If you are not already logged in, click the Login and log in with your TradeLens credentials (ID and password).

   

2. For this example, we will create an Organization subscription. Click on the POST .../subscriptions/org to expand the API. Read through the description, example, and Example Value | Model. We will be creating a webhook that will receive events and send notifications (JSON) from the TradeLens platform to your client system. A webhook is simply a URL (HTTPS) pointer to your client code that must be running and ready to receive events from the platform.

   

3. Click on Try it out (ensure you logged in - see step 1). This will enable you to alter the example input with your own data. You can also click on Model to see an explanation for the input parameters. When you are ready to enter your data, ensure you are in the Edit Value view.

   

   Enter a Name (optional), and the URI for your webhook. The URI must specify HTTPS. For our simplified example, we are going to use a test webhook. In a real scenario, you must have your own code ready to receive data at your webhook URI.

   Alter the input data and click Execute to submit the subscription to the platform.

   

   You should see a successful creation in the response:

   

   Once you have created your event subscriptions, you can work with them using the additional API operations like Get, Delete, Put, and Patch.

Test a Subscription

1. Navigate to the URI of your webhook by entering the URI into your browser. You can also click on the URI from the Shipment Manager > Subscription Management section to show the subscription in the browser.
   

   Note: When this documentation topic was written, if you use the Firefox browser, it has a built in JSON viewer that will format out the events sent to your subscription. Other browsers might have JSON viewers available.

   You should see any events that have been sent to your subscription. If you do not see any events, or want to test sending a new event to the TradeLens platform and ensure that it appears on your webhook, then go to the next step.

2. For this example, our organization will be a carrier and we will create the consignment. The events will be sent to our organization subscription. If the carrier adds another organization as a party to the consignment, then that other organization would receive the events to their subscription. We start by sending a new event to the TradeLens platform using the Swagger API. See API User Guide for the URL links to the Swagger.

   We will use the POST .../consignments - Start consignment tracking (E468) event in our example.

   Select the Event Publish API in the top right area Select a definition. Click Login if you are not already logged in, and enter your TradeLens credentials (ID and password).

   

   Click on the POST .../consignments - Start consignment tracking (E468) API in the Consignments section to expand it and read through the description, example, and Example Value | Model.

   

   Click on Try it out, modify the sample event body with your test data, and click on Execute to run the API.

   

   Check for a "success" response to make sure the event was submitted to the platform. Note that this does not necessarily mean that the processing is complete for the event, it just means that the event was submitted.

   

   Refresh the browser where you were monitoring the webhook subscription and you will see the payload that was passed to the webhook. As mentioned earlier, the Firefox browser has a built in JSON viewer that will format out the events sent to your subscription. Other browsers might have JSON viewers available.

   JSON formatted data:
   

   Raw event data:
   

How Events are sent to Subscriptions

The TradeLens platform will send events to your webhook based on the type of subscription you have created.

Consignments created before a port or a terminal organization is onboarded onto the TradeLens platform will not be visible to the port or terminal unless the carrier does a partyAdded, POST ...​/consignments​/partyAdded - Consignment visibility added (E001), to add the organization to the consignment. This is because TradeLens uses the transport plan for dynamic routing and adds the port and terminal organizations at the time of dynamic route calculation and does not go back and add organizations if they are onboarded later.

The webhook will receive events from the TradeLens platform as a JSONArray, for example:

[
    {
      "eventSubmissionTime": 1523633968187,
      "eventType": "actualDischargeFromBarge",
      "originatorId": "origninatorId",
      "eventOccurrenceTime": 1523633968187,
      "originatorName": "originatorName",
      "transportEquipmentId": "6c995b93-ddf8-4062-a519-99db31a111ef",
      "equipmentNumber": "Test-V1-T003-1523633966168-C1",
      "transportationPhase": "Transshipment",
      "associatedConsignmentIds": ["ConsignmentId1", "ConsignmentId2"],
      "location": {
          "type": "UN/Locode",
          "value": "NLRTM"
      }
    }
]

Currently, this array of events is an array of size one. The message format is an array so that TradeLens could publish multiple events in the future with just one call.