Event Subscriptions (Notifications)

Logivity uses REST webhook callback mechanism to inform organizations about any transactions written to blockchain. You will subscribe to your multi member node's REST Proxy and be notified of events by a callback request sent to your public, protected REST endpoint.

Two types of events are currently supported:

1. Connect Events – Supported by Logivity Connect.

For Logivity Connect channel, the currently supported events are:

Event’s Name	Format ( Events only)
CreateShipment	(CreateShipment)
CreateTransportStatus	(CreateTransportStatus)
AppendAttachment	(AppendAttachment)

There can be one subscription per event name or you can have all events in one subscription Example :
{"event":"(CreateShipment)"} to subscribe to Create Shipment Events.
{"event":"(CreateTransportStatus)"} to subscribe for Create Transport Status events. For events generated by carriers (like Booking Accepted, POP, POA etc.), notification is sent to the shipper. For events created by shipper (Booking canceled) notification is sent to carrier. In case you want to receive the event notification in case of the status update done by other organization (For e.g. as a carrier you want to receive notification in case you accept the shipment), reach out to Logivity Support to enable it.
{"event":"(AppendAttachment)"} to subscribe to notification in case the document is attached to the shipment. If shipper attaches the document then event is generated for carrier and if carrier attaches the document then event is generated for this shipper.
{"event":"(CreateShipment|CreateTransportStatus|AppendAttachment)"} to subscribe to all notifications.

NOTE: kindly make sure you always include brackets () for event name

2. Loadboard Events – Supported by Logivity LoadBoard

For Logivity Loadboard channel

For Loadboard Events, “EventName” field is not present. Event name (CreateShipment, CreateTransportStatus etc.) can still be extracted from the payload (“Payload” field). However, no recipient information is accessible (hence the name: Loadboard Events”).

Please note, that only events, that are generated during the lifetime of a subscription will be sent to you. If you delete your subscriptions, and new transactions are written to blockchain , then you will not be notified of the related events.

Once you create a subscription the Blockchain Rest Proxy will guarantee delivery to your endpoint with respect to the retry mechanism implemented and described below.

Please be aware a new subscription is always validated by a test request (to check the endpoint you provided is up and ready) and requires an appropriate response from your service.

The event callback requests can be secured with mTLS - such security can be omitted during early development; however, it is recommended to implement it for both test and production deployments.

You will not receive any notifications if your subscription is expired - it's expected Carriers will implement a simple subscription management refreshing the subscription every time it's invalid.

NOTE: Events can be lost/missed for several reasons (not active subscription, problem with the endpoint receiving callbacks, etc.). In such a case, one can use “Events Replay” functionality to subscribe to events from the past and “replay” them.

The details of this mechanism are covered in a separate document.

Basic Flow for event subscription:

Create authentication token
Subscribe to notifications
Acknowledge a test callback request
List my subscriptions
Receive notifications (during lifetime of the subscription)
Delete my subscriptions

Below are the details of each step of the flow:

1.Create authentication token

Obtain the authentication token as described in previous section and use the value returned in access_token field in the remaining steps of the flow (as Bearer Authentication). The same authentication token can be used in subsequent calls until the token’s expiry.

2.Subscribe to notifications

In order to subscribe to notifications, you need to expose public REST endpoint, which can be secured either using mTLS authentication or oAuth authentication.

Note: Please note, that a {subscription-channel} part in the subscription URL is different for Logivity CarrierConnect and Logivity Loadboard ({cc-channel} and {lb-channel} respectively).
The same holds true when it comes to a value of a “chaincode” field in the payload ({subscription-chaincode}).
Below are examples for Logivity Connect ({subscription-channel} = {cc-channel}, {subscription-chaincode} = “ccshipments”). For Logivity Loadboard it should be: {subscription-channel} = {lb-channel}, {subscription-chaincode} =”loadboard”.

2.1 Securing Event Notification: Event callbacks from Logivity can be secured using one or more of following methods

IP Whitelisting
mTLS Certificates
oAuth Token

Note: Event can be received without any of these security but it is highly recommended to use one or more combinations of above methods to secure the connections

2.2 Create subscription request using mTLS:

Note:
1. (type)
1.Connect Events: always “chaincode”
2.Loadboard Events: always “privateChaincode”.

(callbackURL) - Your public callback (webhook) address. For testing proposes you can generate a unique callback URL and test it on this site: https://webhook.site .
(maxCallbackRetry) - the maximum number of attempts REST proxy will try to send the notification, before logging the event as lost. After 7 attempts the interval between attempts following will be 2 minutes. For instance, maxCallbackRetry=720 will result in retries being sent up to 1 day. It's required to use a value that will accommodate any downtime you predict; events will be lost after maxCallbackRetry is exceeded.
callbackTLSCerts - an optional json node (can be ommited). It will enable callback server mutual authentication, and will be used by the REST proxy to send all notifications during establishing of the SSL channel
1.(ca_certificate): Callback server's CA certificate. It will be used by Rest Proxy to verify the callback server. The certificate must be in PEM format.
2.(client_private_key) and (client_certificate): Client certificate that will be used as Rest Proxy's certificate when connecting to the callback server. The certificate must be in PEM format. The private key and the client certificate are concatenated, and stored in single line (new lines are coded as \n).
(expires) - in production environment can be set to a very long duration ie. “3560d” (10 years), during development shorter intervals can be used ie. 1m (1 minute), 1h (1 hour), 1d (1 day)
(event)
1.Loadboard Events: always {"event": “.*” }
2. Connect Events Examples:
{"event": "(CreateShipment)"}
{"event": "(CreateShipment|CreateTransportStatus)"}

Note:
In case of ”webhook.site” is used, it should be kept in mind, that data sent to the site, is available to everyone who knows the callback url. For example if we set callbackULR to:
https://webhook.site/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Anyone knowning this URL can intercept the messages. This can be avoided by using paid version of the service or custom URL listeners.

2.3 Create subscription request using oAuth:
You can provide the details of your oAuth server which will be used to get the token before making the call to your callback url to send the events

Note:
1. (type)
1.Connect Events: always “chaincode”
2.Loadboard Events: always “privateChaincode”

(callbackURL) - Your public callback (webhook) address. For testing proposes you can generate a unique callback URL and test it on this site: https://webhook.site
(maxCallbackRetry) - the maximum number of attempts REST proxy will try to send the notification, before logging the event as lost. After 7 attempts the interval between attempts following will be 2 minutes. For instance, maxCallbackRetry=720 will result in retries being sent up to 1 day. It's required to use a value that will accommodate any downtime you predict; events will be lost after maxCallbackRetry is exceeded.
callbackTLSCerts - an optional json node (can be ommited). It will enable callback server mutual authentication, and will be used by the REST proxy to send all notifications during establishing of the SSL channel
1.(ca_certificate): Callback server's CA certificate. It will be used by Rest Proxy to verify the callback server. The certificate must be in PEM format.
2.(client_private_key) and (client_certificate): Client certificate that will be used as Rest Proxy's certificate when connecting to the callback server. The certificate must be in PEM format. The private key and the client certificate are concatenated, and stored in single line (new lines are coded as \n).
oAuth_ClientId – ClientId from the oAuth server to be used for getting token
oAuth_ClientSecret – ClientId from the oAuth server to be used for getting token
oAuth_TokenURL – Token URL of the oAuth server
oAuth_Scope (optional) – Scope URL as defined in the oAuth server
(expires) - in production environment can be set to a very long duration ie. “3560d” (10 years), during development shorter intervals can be used ie. 1m (1 minute), 1h (1 hour), 1d (1 day)
(event)
1.Loadboard Events: always {"event": “.*” } 2.Connect Events Examples:
{"event": "(CreateShipment)"}
{"event": "(CreateShipment|CreateTransportStatus)"}

3. Acknowledge a test callback request.

The moment you subscribe, the REST proxy will call back with the following test request:

Area	scope
Source IP	All event notifications are sent from IP address 138.1.45.154 Use this IP address when using IP whitelising as your chosen security method (2.1.1)
Method	POST
Payload	`{ "type": "TEST" }`

Required acknowledgement response from your service is:

Area	scope
Http Code	200
Payload	N/A

4. List my subscriptions

examples found in API files

5.Receive notifications

Blockchain chaincode events are generated for each business event like creation of a shipment. The event will be captured in a JSON structure like the one below.

For Connect Events, the EventName will store the name of an event in the prefix, then underscore separator followed by the Logivity ID.
For Loadboard Events, the name of an event can be found in “Payload” attribute, the top key in the decoded JSON (example payload provided below).

It is important carriers store the transaction identifier (TxID) and BlockNumber for reference (in case of problem diagnosis).
The Payload stores a base64 encoded JSON payload that is the object holding only minimum Data related to the asset. Carriers need to decode the encoded payload and extract appropriate field node text value and use it to fetch the full object from Blockchain.
For example, the "Cargo"->"AssetId" node text value (which looks like Cargo_carrier-connect-dummy_973da3acbc914ff58f678439d30e628695b8460499a4a90d7b8c6762896e030c) should be used as parameter to the GetShipmentByCargoId function call.

Please note “sourceURL” field . This will be used, later on, in GetShipmentByCargoId, GetTransportStatusById calls.

Required response from your service is:

Area	scope
Http Code	200
Comment	Response should be sent within 5 Seconds otherwise system assumes that message has failed and try to resend it again.
	It is recommended that you send the Http 200 response immediately after receiving the message and process it further as Async transaction

6. Delete my subscriptions

Notes: (username) - the same username used to create authentication token

The expected response provides confirmation that the specific list of subscriptions has been deleted.