Skip to content

IPN Webhook Safelisting API

The IPN Webhook Safelisting process consists of two steps:

Step 1:

Method: POST

Path: https://amazonpay.amazon.in/v1/ipn

Description: This API is used to safelist the webhook URL for receiving the IPN (Instant Payment Notification). In return, merchant will get “200 OK” if the IPN is successfully safe listed for the given webhook URL.

Request Parameters

Parameter Name Data Type Description Mandatory Constraints
merchantId String Merchant ID provided by Amazon Yes
recipientIdentifier String Merchant ID provided by Amazon Yes
recipientType String Recipient Type Yes Allowed value: "MERCHANT"
recipientEndpoint Set Merchant Webhook URL Yes Max length of 2048 characters
recipientEndpointType String Recipient endpoint type Yes Allowed value: "HTTPS"

Request Samples

{
    "merchantId": "AMAZONMID12",
    "recipientIdentifier": "AMAZONMID12"
    "recipientType": "MERCHANT",
    "recipientEndpoint": "https://www.merchantwebhook.in",
    "recipientEndpointType": "HTTPS",
}

Response Parameters

Note

For successful invocation, no response body is returned.

Sample Response

Response State HTTP Status Code Response Body
Success 200 OK Empty response body
Error 400 

{
"code": "InvalidArguments",
"message": "merchantId field is mandatory, cannot be null or blank"
}

Common Errors

Status Code Code Type Message
400 InvalidArguments recipientEndpointType must be one of following: [HTTPS]
400 InvalidArguments recipientType must be one of following: [MERCHANT]
400 InvalidArguments recipientIdentifier field is mandatory, cannot be null or blank
400 InvalidArguments The recipient endpoint provided is incorrect
400 InvalidArguments The recipient Identifier provided is not supported. Please try again.
400 MerchantIdMismatch Specified merchant id does not match with x-amz-client-id header value.
401 AuthorizationExpired Specified Signature has expired
401 AuthorizationFailed Specified Signature is invalid
403 LimitExceeded Maximum limit of subscriptions reached.
404 IdentifierNotFound The recipient Identifier provided does not exist. Please try again.
500 InternalServerError An internal server error has occurred. Try your request again later.

Step 2:

Once you call the IPN Webhook Safelisting API, you will receive a Subscription Notification response to your server. This response contains a subscription URL to which you should make an HTTP GET call from your server to confirm the subscription. This will help avoid any manual intervention in IPN safelisting.

Subscription notification will have the Type as “SubscriptionConfirmation”

Note: Upto 5 webhooks can be safelisted for an MID.


{
   "Type": "SubscriptionConfirmation",
  "MessageId": "875ae797-af2b-5da8-8d13-bff8c2173406"
  "Token": "xxxxxx",
  "TopicArn": "arn:aws:sns:ap-south-1:556148052840:IOPN_",
  "Message": "You have chosen to subscribe to the topic arn:aws:sns:ap-south-1:556148052840:IOPN_...",
  "SubscribeURL": "subscription-confirmation-url",
  "Timestamp": "2025-09-06T04:12:52.582Z",
  "SignatureVersion": "1",
  "Signature": "s3si+xf48hmqzW2a79FMCwm5Z9HymreeqYM7wCVxxxxxxxxxxxxxx",
  "SigningCertURL": "https://sns.eu-west-1.amazonaws.com/SimpleNotificationService-433026a4050d206028891664da859041.pem"
}