Push Notifications - Obtain Secure Delivery OTPs

By setting up a push notification webhook, shippers and integrators in the India (IN) marketplace can obtain Secure Delivery OTPs from Amazon Shipping. An OTP is generated for each eligible tracking ID, applies to both forward and reverse shipments, and remains valid until the end of the day.

Steps to Subscribe to Push Notification Feature

The shipper/integrator needs to provide their
- Webhook URL
- Authentication Mechanism
- Shipper Account ID or Shipping Party Account ID (for whom push notifications are being setup)
- Point of contact emails.
Once these details are shared with the Account Manager they will be able to request webhook subscription setup.
The Account Manager will internally coordinate configuring and activating the subscription for notifications.

Supported Authentication Mechanisms

One of the following must be enabled by the Shipper/Integrator:

#	Method	Description	Example
1	API Key	A token sent by Amazon in the request headers when delivering tracking information to your webhook URL.	`X-API-KEY: abcdef12345`
2	Query Parameter	A key-value pair passed in the URL. Useful when you want to express a request entirely in a URL.	`https://example.com/webhook?X-Amz-Credential=<your-access-key-id>`
3	Username & Password	A key-value pair passed in the header to authenticate the incoming request via username and password.	Basic Auth header
4	OAuth 2.0	Open Authorization framework. Amazon obtains an access token via OAuth 2.0 Client Credentialsflow and presents it when calling your webhook.	Bearer token in Authorization header

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	integer (epoch ms)
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 (enum)
eventCode	Denoting the state of the OTP event	string (enum)
appId	Internal PushNotification System Attribute.	string

Sample event:

{
  "version": "0",
  "id": "f65df375-c5fa-4b03-9d62-bfb91f69ed34",
  "detail-type": "PN Event",
  "source": "AmazonShipping",
  "account": "644864979882",
  "time": "2026-09-18T11:47:21.037309157Z",
  "region": "eu-south-2",
  "resources": [
    
  ],
  "detail": {
    "verificationCode": "781430",
    "verificationCodeTTL": 1789775999000,
    "trackingId": "372638820962",
    "eventCode": "PIN_GENERATED",
    "shipmentType": "FORWARD",
    "version": 1,
    "appId": "default-app-id"
  }
}

{
  "version": "0",
  "id": "a31bb96a-733d-49f9-a983-c4a4924e3fa2",
  "detail-type": "PN Event",
  "source": "AmazonShipping",
  "account": "644864979882",
  "time": "2026-09-22T03:08:16.838662675Z",
  "region": "eu-south-2",
  "resources": [
    
  ],
  "detail": {
    "verificationCode": "126183",
    "verificationCodeTTL": 1790121599000,
    "trackingId": "372714630867",
    "alternateLegTrackingId": "515241446031",
    "eventCode": "PIN_GENERATED",
    "shipmentType": "REVERSE",
    "version": 1,
    "appId": "default-app-id"
  }
}

FAQ

What is the need for push notifications to obtain the OTPs?
It enables shippers and integrators to receive Delivery OTPs at their configured webhook endpoint for eligible shipments, on both the forward and reverse legs.
Who can enable OTP Push Notification feature?
Third-party integrator and directly integrated shippers who use the Shipping V2 APIs to create shipments with Amazon Shipping can use this feature to receive notifications with Delivery OTPs.
Are HTTPS webhooks required?
Yes. HTTPS is mandatory for all webhook URLs. Amazon configures HTTPS-enabled endpoints only, to secure communication and protect sensitive data in transit.
How long does it take to enable push notifications?
Push Notifications are configured via our technical team. You will receive a response within 5 business days.
My webhook is returning 401 Unauthorized — what's wrong?
Common causes:
a. API key mismatch — Verify the key-value pair matches what was configured during onboarding.
b. OAuth token expired — Ensure your OAuth endpoint issues tokens with a sufficient TTL.
c. Incorrect Basic Auth credentials — Verify the username and password match your endpoint's configuration.
I'm not receiving any events after subscribing — what should I check?
a. Verify your endpoint is publicly accessible (not behind a VPN or firewall).
b. Ensure your endpoint returns an HTTP 2xx response to POST requests.
c. Confirm your authentication credentials are valid and current.
d. Contact your Amazon account manager to verify your subscription is active and enabled.