Push Notifications - Tracking a Shipment

Push Notifications (WebHook) is a Tracking feature enabled by Amazon Shipping which helps shippers/ integrators to automatically receive shipment tracking updates for a package as they become available, without the need to make any external API calls.

The push notifications feature allows developers (shippers/ integrators) to subscribe to Amazon tracking updates via their webhook URL endpoint. At present developers will be manually onboarded to receiving push notifications, however Amazon is working to enable self-service API subscriptions.

Steps to subscribe to Push Notification feature:

1. The shipper/ integrator needs to provide their Webhook URL, Application ID, Shipping Party Account ID (for whom push notifications are being setup), and their technical point of contact to their integration POC within Amazon.
2. Once these details are shared with the integration POC, they will be able to subscribe the developer to receive push notifications for the shared shipping party account id.
3. 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):

1. 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 Authentication for more details.
   Example: X-API-KEY: abcdef12345
2. 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 Authentication for more details.
   Example: https://s3.amazonaws.com/examplebucket/test.txt?X-Amz-Credential=
3. 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.
4. 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:

{
  "version": "0",
  "id": "2d1cf554-e7f0-2362-6b2d-dd36bd4677e2",
  "detail-type": "Tracking Detail",
  "source": "AmazonShipping",
  "account": "434519225125",
  "time": "2023-01-23T11:09:42Z",
  "region": "eu-west-1",
  "resources": [],
  "detail": {
    "shippingPartyAccountId": "A1QW4MEBU0BWQI",
    "trackingId": "test_tracking_id",
    "eventTime": "2023-01-16T15:39:23Z",
    "status": "InTransit",
    "alternateLegTrackingId": "65665589589",
    "eventCode": "PickupDone",
    "appId": "amzn1.sp.solution.4622520d-ef11-4366-aa17-5ff8bb0b9aea",
    "shipmentType": "FORWARD", // [New] field that indicates a packages forward or reverse journey 
    "trackingDetailCodes": [
            "DeliveredToPorch" // [New] This provides additional details about a shipment.
    ], 
    "version": 2,
    "timeToLive": 1679569781
  }
}

FAQ

1. What is the need for push notifications?

Using push notifications helps shippers to automatically receive shipment status updates for a package as they become available, without the need to make any external calls. Using the push mechanism additionally helps to minimize throttling risks.

2. Who can enable Push Notification Tracking feature?
3rd Party Integrators and direct integrated shippers who are using Shipping V2 API to create shipments for Amazon Shipping carrier can use this feature to get tracking notifications and updates of their shipments.

3. In the event of a system outage, can previous notifications be requested?
In the event of an outage, the shipper will be able to request previous tracking information via the existing pull API.

4. Is there a difference in the available fields between the pull API and push notifications?
Yes. As of today, we are not pushing “location” and “promisedDeliveryDate” as a part of the payload for push notifications. Additionally, the pull API response includes the full event history for every call, while the push notification is sent for each new event, and contains only that event.

5. Is there a difference in the tracking data between the pull API and push notifications?
No, the data will be the same between the two systems.

6. Where can I find a list of tracking status and event codes ?
Event Codes and tracking status list is available in our FAQs, Please refer TrackingStatus documentation.

7. What details does Shipper/ Integrator needs to provide to enable Push Notification ?
Webhook URL: Sample Webhook : https://tracking.notification.co.uk/webhook_integrations/amazon-shipping/
Application ID : amzn1.sp.solution.dc3gh3fc-ee33-4z74-c2c4-u1234567890r (AppId can be found within the Developer Central/ Seller Central Application)

Shipping Party Account ID : Shipper or Integrator's customer's shipping Account ID or Name (Example :
Customer name : "NewShipper" and accountId : AC123TY7890).
Authentication Method : Example APIKey : 93GSRq06Pmf5e@fAhq$$6lo^ (validity : never expire)

8. Are HTTPS webhooks required for Push Notification Tracking?
Yes, HTTPS is a mandatory requirement for webhook URLs used with the Push Notification Tracking feature. Amazon will only accept and configure HTTPS-enabled webhook URLs to ensure secure communication and protect sensitive tracking data during transmission.

9. How long does it take to enable the push notifications?
Push Notifications are now being configured via our tech team, so you will receive a response from us within 5 business days.

10. How can Shipper/ Integrator request for Push Notification Tracking?
Push Notification can only be enabled for orders shipped with Amazon Shipping. As the subscription process is manual as of today, please contact your Amazon Account Manager for further assistance to enable Push Notification Tracking feature.