Skip to content

Setting up Subscriptions

Copyright IBM Corporation and Maersk GTD Inc. 2018, 2019

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:

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

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

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

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

  • Delegation ID: subscribes to either import events, export events, or all events for a specific consignment or transport equipment. The delegation IDs are returned on the "POST .../consignments - Start Consignment Tracking (E468)" and "POST .../transportEquipment - Start Transport Equipment Tracking (E278)" events and the appropriate one (import, export, all) is used to set up the subscription.

The role of your organization determines the subscription type you can access. Organization and delegation ID subscriptions can be set up if you are a member of the organization, or if you have the delegationId for the consignment or transport equipment. 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 each port, 5 for each country, 5 for your organization, 5 for each terminal, and 5 for each delegation ID. For example, if an organization is subscribed to 3 different ports and has 5 subscriptions for each port, they would have 15 port subscriptions.

Webhook and Shared Secret

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 platform will publish events to your webhook using a HTTPS POST request. Your webhook must return an HTTP success code (2nn) response to that call when you receive the event. If you are creating a port, country, or terminal subscription, you can only pass a port, 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. You can subscribe to a given delegation ID if you have the delegation ID from the "POST .../consignments - Start Consignment Tracking (E468)", "POST .../transportEquipment - Start Transport Equipment Tracking (E278)", or if it was shared with you from a user or a system that started the consignment or transport equipment.

The platform protects itself against misbehaving webhooks. If a webhook consistently takes more than 10 seconds to return any response then the platform will blacklist the webhook, meaning the publishing of events to your webhook will stop for a period of time, escalating up to one hour. Your webhook should return some kind of HTTPS response within 10 seconds. If your service requires more than 10 seconds to process some events, it is recommended that the webhook responds to the HTTPS request to confirm you have received the event before you begin processing the event.

A webhook can 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, as an attacker who can compromise one key would gain access to all your subscriptions simultaneously.

  • 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).

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 Subscription Management in the top menu.
    Setting Up Subscriptions26c

  3. Click Create Subscriptions.
    Setting Up Subscriptions3c

  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 (port, country, organization, terminal, delegation ID). For our example we will select Organization Subscriptions.
    Setting Up Subscriptions4c

  5. Enter a Name (optional), Shared Secret (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.

    The Shared Secret is used to enable encryption and decryption between the TradeLens platform webhook and your system. Details on Shared Secrets are provided in Swagger.

  6. Click Create Subscription.
    Setting Up Subscriptions5n

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, Organization, and Delegation ID subscriptions. Note that this process can be done through your client code by calling the Platform Subscription APIs directly, see the API Documentation 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 Subscription API in the top right area Select a spec. Then click the Login and log in with your TradeLens credentials (ID and password).

    Setting Up Subscriptions13a

  2. For this example, we will create an Organization subscription. Click on the POST /api/v1/subscriptions/org to expand the API. Read through the description, example, and Example Value | Model. You 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.

    Setting Up Subscriptions16a

  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.

    Setting Up Subscriptions16b Setting Up Subscriptions16c Setting Up Subscriptions16d

    Enter a Name (optional), Shared Secret (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.

    The Shared Secret is used to enable encryption and decryption between the TradeLens platform webhook and your system. Details on Shared Secrets are provided in Swagger.

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

    Setting Up Subscriptions16f

    You should see a successful creation in the response:

    Setting Up Subscriptions20a

    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.
    Setting Up Subscriptions6m

    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 Documentation 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 spec. Click Login if you are not already logged in, and enter your TradeLens credentials (ID and password).

    Setting Up Subscriptions13c

    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.

    Setting Up Subscriptions14c

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

    Setting Up Subscriptions11c

    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.

    Setting Up Subscriptions12c

    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:
    Setting Up Subscriptions7n

    Raw event data:
    Setting Up Subscriptions8c

How Events are sent to Subscriptions

The TradeLens platform will send events to your webhook based on the type of subscription you have created. If you set up a delegation ID based subscription and there are events that have already occurred for the consignment or transport equipment, the platform will send all of the previous events to your webhook immediately for that delegation ID. This ensures that the subscription is up to date. The platform bundles the multiple events into an array and sends them as a single HTTPS message. The list of events sent is very unique to that subscription. For example, if right after that list of events is sent, a new event for the same consignment arrives, it would be sent to your webhook. Then, if another subscription is created for that consignment (similar to the one that you had), a different set of events would be sent to it: the old set sent to your first subscription along with the additional event received since then. Delegation ID subscriptions receive the array of previous events for the delegation ID. Other subscription types like organization, port, country, and terminal, do not receive previous events. If an event is sent to a errant webhook (either it is down, or responds with an error code), the platform will not retry sending that event.