How do I troubleshoot HTTP or HTTPS endpoint subscription notification issues to my Amazon SNS topic?

Resolution

Before you subscribe your HTTP/HTTPS endpoint to an SNS topic, you must confirm that the HTTP/HTTPS endpoint is ready to process Amazon SNS messages.

Verify that your HTTP/HTTPS endpoint is publicly accessible

Amazon SNS doesn't support private HTTP/HTTPS endpoints. Amazon SNS makes an HTTP POST request to your endpoint through the public internet when you subscribe an HTTP/HTTPS endpoint to an SNS topic. For more information, see Parsing Amazon SNS message formats.

To check if your endpoint is publicly accessible, make a POST request from your local machine similar to the following:

curl -X POST your_HTTPS_endpoint -H "Content-Type:text/plain; charset=UTF-8" --data {"x":"y"} -v

Example output:

200 OK

In the preceding output, the endpoint is publicly available with the HTTP 200 OK status code.

If you subscribed an HTTP/HTTPS endpoint that isn't publicly accessible to an SNS topic, then you receive the following error:

"An error occurred (InvalidParameter) when calling the Subscribe operation: Invalid parameter: Unreachable Endpoint"

Important: Your hostname must not contain an underscore.

Validate your endpoint response header

Complete the following steps based on whether you use basic or digest access authentication. Be sure that your endpoint is HTTPS and supports the HTTP/1.1 401 Unauthorized header response.

Basic access authentication

When your endpoint receives an unauthenticated request, it returns the HTTP/1.1 401 Unauthorized header response along with a WWW-Authenticate header. The header value must contain the keyword Basic similar to the following:

WWW-Authenticate: Basic

For more information, see RFC 2617 on the RFC Editor website.

Digest access authentication

When your endpoint receives an unauthenticated request, it returns an HTTP/1.1 401 Unauthorized header response along with a WWW-Authenticate header. The header value must contain the following:

• the keyword Digest.
• a randomly generated single-use nonce value.
• an authentication realm.
• other optional parameters supported in RFC 2617 on the RFC Editor website.

Example header value:

WWW-Authenticate: Digest realm="testrealm@host.com",
                        qop="auth,auth-int",
                        nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093",
                        opaque="5ccc069c403ebaf9f0171e9517f40e41"

Set up delivery status logging

Complete the following steps:

1. Set up delivery status logs for your SNS topic.
2. View the log data for your SNS subscription confirmation notification delivery that's generated when you subscribe an HTTP/HTTPS endpoint.

Example failure log output:

sns/your_aws_region/your_account_ID/your_topic_name/Failure

Note: To see why your subscription confirmation notification failed delivery, check the providerResponse attribute in your Amazon CloudWatch delivery status logs. For more information, see SMS delivery failure reasons.

Check the SSL certificate for your HTTPS endpoint

If you use an HTTPS endpoint, then complete the following troubleshooting steps:

1. Confirm that the SSL certificate returned by the endpoint is valid and signed by a certificate authority trusted by Amazon SNS.

2. Verify that your endpoint returns the complete chain of certificate. The complete chain includes all the intermediate certificates.
   Note: You can use third-party tools to verify if the SSL certificate returned by your endpoint is trusted and complete. For example, you can use SSL Server Test on the SSL Labs website.

3. To verify if the SSL certificate returned by your endpoint is trusted and complete, run the following OpenSSL command:

   openssl s_client -connect yourHostname:443 -servername yourHostname -showcerts

   Example failed SSL certificate providerResponse in CloudWatch logs:

   {
       "notification": {
           "messageId": "...",
           "topicArn": "arn:aws:sns:ap-northeast-1:***:***",
           "timestamp": "2021-05-12 06:41:20.778"
       },
       "delivery": {
           "deliveryId": "***",
           "destination": "https://***",
           "providerResponse": "SSLPeerUnverifiedException in HttpClient",
           "dwellTimeMs": 66171,
           "attempts": 4
       },
       "status": "FAILURE"
   }

Check if a firewall is blocking your HTTP/HTTPS endpoint

If a firewall prevents the delivery of the SNS subscription confirmation notification to your HTTP/HTTPS endpoints, then allow the AWS Region specific IP addresses.

Check if your HTTP/HTTPS endpoint has a subscription filter policy

If your endpoint is in a subscribed state but didn't receive topic notifications, then check if your endpoint has a subscription filter policy configured. If your HTTP/HTTPS subscription has a filter policy, then the policy might filter notifications.

To confirm that your SNS messages got filtered, check the CloudWatch metrics NumberOfNotificationsFilteredOut, NumberOfNotificationsFilteredOut-InvalidAttributes, and NumberOfNotificationsFilteredOut-NoMessageAttributes.

For more information, see How do I troubleshoot message filtering issues in Amazon SNS?