Parcel events push notification

Events are generated for the parcels flowing through the distribution networks. For the parcels you are entitled to get information about, you can request that DI provides you with push notifications when new events arrive. This document describes:

the feature of push notification for parcel events as delivered by DI
what you, or you company, have to do before you can use this feature
how you request to have this feature enabled

Content

1 DI Push Parcel event Service
2 Required actions to enable feature
- 2.1 Granting access to your queue
- 2.2 Identifiers
3 Example payload delivered to queue
4 References

DI Push Parcel event Service

The DI Push Service delivers new events as they arrive to an Amazon Web Services (AWS) SQS queue. Only events for parcels associated with your company/entity are delivered to your queue. DI is responsible for managing this routing functionality.

The target queue can live in two difference places:

in your own AWS account. This gives you as a customer the most flexibility.
in DI's AWS account. A fee will be charged in this case to cover administration and operating costs. For this option reach out to you contact person to plan.

The events will be represented in the same format as used by the Parcel Event Log v1 API, but not including all fields/values.

Clients using this API should not fail if new fields are added to the response. If a new field is added to the response on a later stage, existing clients should handle this in a way such as they just ignore the field.
Fields not set in the response are not left out, that is fields in the response may have null values. E.g. "shipmentNumber": null. The client using the endpoint should handle this.
Event may be delayed for a short periode of time and events may come in incorrect order (e.g if there are delays from a specific source). Clients should handle this by using the event time specified for each event, and not necessarily present them in the order they are received.

Required actions to enable feature

As a user of the service you must:

ensure your organization is ready to process events: fetch them from the queue, parse them, and process them.
See [1] for a list of available implementation technologies from AWS. Examples are included in the SDK documentation.

Option 1a

(preferred) provide the destination AWS default type SQS queue ARN (FIFO queues are not supported)
- grant DI access to your queue (see section below)
- confirm the subscription to the SNS topic for your SQS queue after DI has enabled the feature (see [2]). You need to find and visit a subscription confirmation URL inside a message posted to your queue.
- if you can't find subscription confirmation message, double check the policy to ensure DI is allowed to write into your queue and ask DI to resend the confirmation message
- This option includes automatic retry logic if you queue for some reason is unstable

Option 1b

(preferred) provide the destination HTTP/HTTPS protokoll endpoint (e.g. from google cloud services)
- Whitelist DI to give access to send information (see section below)
- Make sure your endpoint accepts messages in text format
- Confirm the subscription to the SNS topic for your endpoint after DI has enabled the feature (see [2]). You need to find and visit a subscription confirmation URL inside a message posted to your endpoint.
- For http/s we will handle a maximum of 3 retries.

Granting access to your queue

Option 1

DI needs to be allowed to write messages onto your queue. In AWS, this can be done with the following complete policy:

{
  "Version": "2012-10-17",
  "Id": "SomeId",
  "Statement": [
    {
      "Sid": "SomeSid",
      "Effect": "Allow",
      "Principal": {
        "AWS": "*"
      },
      "Action": "SQS:SendMessage",
      "Resource": "arn:aws:sqs:{CUSTOMER-REGION}:{CUSTOMER-ACCOUNT}:{CUSTOMER-QUEUE-NAME}",
      "Condition": {
        "ArnEquals": {
          "aws:SourceArn": "arn:aws:sns:{DI-REGION}:{DI-ACCOUNT}:{DI-TOPIC-NAME}"
        }
      }
    }
  ]
}

If you have other permissions on the queue, what you need to do is to add the block inside the Statement-element to your own existing policy.
We use awsv4 auth-type

Option 2

It is optional to have a public endpoint, but if you want a private one remember to give access to DI.
This is set up differently based on the infrastructure and technology on you side. Here are useful links or examples

Example use of Node.js to validate that the message is from AWS-SNS - https://www.npmjs.com/package/sns-validator
Validate on topic to verify it is from the correct sender
Example for converting AWS SNS to GCP pubsub - https://github.com/GoogleCloudPlatform/community/blob/master/tutorials/cloud-functions-sns-pubsub/index.js

Identifiers

The table below lists the identifiers needed to construct the correct ARNs for the policy.

Environment	Region	Account	Topic name

Environment	Region	Account	Topic name
Staging	eu-west-1	163369885595	parcel-events-push-topic
Production	eu-west-1	022383231344	parcel-events-push-topic

Example payload delivered to queue

{
   "Type":"Notification",
   "MessageId":"efa878c6-8465-59ae-9c73-2dd57c10088d",
   "TopicArn":"arn:aws:sns:eu-west-1:081098945233:parcel-events-push-topic",
   "Message":"{\"events\":[{\"shipmentNumber\":\"70724761431111111\",\"trackingNumber\":\"370724761411111111\",\"eventTime\":\"2019-01-22 14:38:00\",\"lat\":62.0,\"lon\":98.0,\"locationContext\":\"Somewhere\",\"eventType\":{\"apiKey\":\"103\",\"description\":\"A notification with delivery information has been sent to the customer\"},\"additionalInfo\":{\"apiKey\":\"001\",\"description\":\". Our carrier attempted to deliver your shipment, but was unfortunately unable to locate the delivery address\"},\"eventGroup\":{\"id\":3,\"name\":\"event.type.group.communication\"},\"comChannelType\":\"EMAIL\",\"changeUserId\":null,\"regSystem\":null,\"message\":\"Test message\"}]}",
   "Timestamp":"2019-03-26T09:51:49.664Z",
   "SignatureVersion":"1",
   "Signature":"q5Ao97VRqZVc6BybwuOLjFfhiNE/WXTpqR53RUdxDnRSh5n9znKzMbZaliY2ovFifmEEQYTAbRH8bt65Xisv+6qRJKdWawwvkhg4+wS0+AOi2xycVVNvcddBqRnuA0al8Unz9lUabVrEQLyI0eOwVZFMo2SZSorDxHge+sqyeLOXjo9m6/QCIIVGPowy6PUZ/2WOIvpcp1+mgJn6rolvM7YxUs609nATesPpWA/9r8HAOUVk9Uy/RrL18b0JbqVu+QZhFPKhSHvKqHoZU1kn9Qo7c+Qyluf995r0vQadONeTN7po0iLw5KVH8ybBhg3fN1q3goem1YYfNfiETf3xTw==",
   "SigningCertURL":"https://sns.eu-west-1.amazonaws.com/SimpleNotificationService-6aad65c2f9911b05cd53efda11f913f9.pem",
   "UnsubscribeURL":"https://sns.eu-west-1.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:eu-west-1:081098945233:parcel-events-push-topic:bfe7271c-ca85-4048-87bd-99e7c41cdd0e",
   "MessageAttributes":{
      "ownerPartyId": {
        "Type": "Number",
        "Value": "1"
      },
      "ship2meDelivery": {
        "Type": "String",
        "Value": "false"
      },
      "accessLevel": {
        "Type": "String",
        "Value": "PUBLIC"
      },
      "shopId": {
        "Type": "Number",
        "Value": "1"
      },
      "servicePointDelivery": {
        "Type": "String",
        "Value": "false"
      },
      "freightProductId": {
        "Type": "Number",
        "Value": "15"
      }
   }
}

The data inside the Message element conforms to the Parcel Event Log v1 API.

References

[1] https://aws.amazon.com/getting-started/tools-sdks

[2] https://docs.aws.amazon.com/sns/latest/dg/sns-sqs-as-subscriber.html, see User Who Does Not Own the Queue Creates Subscription.

https://docs.aws.amazon.com/sns/latest/dg/welcome.html