Push Notifications - Secure Delivery With OTP for Reverse Journey

This functionality, provided by Amazon Shipping, enables shippers and integrator to receive OTPs directly through their webhook URL endpoint. An accumulated payload is sent containing multiple tracking IDs with an OTP which has an expiry until the end of day.

Steps to subscribe:

The shipper/integrator needs to provide their Webhook URL, Application ID, Shipping Party Account ID (for whom NDR push notifications are being setup), and their technical point of contact to the integration POC within Amazon.
The integration POC will internally coordinate configuring and activating the subscription for notifications.

Below client identification (Authentication) mechanism is supported for push notifications (One of these has to be enabled by the Shipper/Integrator):

API key - An API key is a token that a client (Amazon) provides while sending tracking information to webhook URL. With API key auth, we send a key-value pair to the webhook endpoint in the request headers. Please refer to API Key Authenticationfor more details.
Example: X-API-KEY: abcdef12345
Query parameter - A key value pair which will be passed in the URL. Using query parameters to authenticate requests is useful when we want to express a request entirely in a URL. Please refer to Query Parameter Authenticationfor more details.
Example: https://s3.amazonaws.com/examplebucket/test.txt?X-Amz-Credential=
Username & Password - it's a key value pair which will be passed in header to authenticate the incoming request via username and password. Please Refer to Username and Password Authentication for more details.
OAuth authentication - The Open Authorization is a flexible authorization framework for securing application access to protected resources. OAuth 2.0 uses access tokens that are presented by client applications (on behalf of the end users) to access the protected resources. Please refer to OAuth Authorization for more details.

Push Notification payload includes the following elements:

Name	Description	Schema
verificationCode	The OTP required by the customer (shipper)	string
verificationCodeTTL	The expiration unix timestamp for this OTP ( will always be end of a day) since OTP is valid until EOD	Unix Epoch timestamp
trackingId	Forward Leg Tracking ID for the shipment being returned	string
alternateLegTrackingId	Reverse Leg Tracking ID for the shipment	string
shipmentType	Denotes the journey or leg type; FORWARD or REVERSE.	string
eventCode	Denoting the state of the OTP event	string
appId	Internal PushNotification System Attribute.	string

Sample event:

{
  "version": "0",
  "id": "48040fd3-3094-24d8-06c8-d97be2024072",
  "detail-type": "PN Event",
  "source": "AmazonShipping",
  "account": "474668380910",
  "time": "2025-01-28T11:14:36Z",
  "region": "eu-west-1",
  "resources": [],
  "detail": {
    "verificationCode": "938492",
    "verificationCodeTTL": 1705190399000,
    "trackingId": "1709913037944",
    "alternateLegTrackingId": "1709912326405",
    "shipmentType": "REVERSE",
    "eventCode": "PIN_GENERATED",
    "appId": "amzn1.aaa.app.qo6jo5stw4pa4wwg7mya"
  }
}

FAQ

1. How long does it take to enable the push notifications?
It takes 7-10 business days to enable the push notifications post receiving the details.

2. How can Shipper/ Integrator request for Push Notification Tracking?

Please write to [email protected] to request for push notification for your use-case.