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
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, in which case this service will be provided free of charge. This also 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.
The events will be represented in the same format as used by the Parcel Event Log v1 API.
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 1
(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 2
(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.
Option 3
(alternative) ask if DI can host the AWS SQS queue if you don't have any plans to use AWS in your organization
Events will be kept for four days before they expire.
Contact your contact person with your carrier to enable this
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 |
|---|---|---|---|
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.