How do I troubleshoot issues when I subscribe an HTTP(S) endpoint to my Amazon SNS topic?

Last updated: 2021-06-21

I can't receive a subscription confirmation notification when I subscribe my HTTP or HTTPS endpoint to an Amazon Simple Notification Service (Amazon SNS) topic.

Resolution

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

Note: The following steps also apply to scenarios where your HTTP(S) subscription is in the confirmed state, but you still aren't receiving notifications.

Verify that your HTTP(S) endpoint is publicly accessible before subscribing to an SNS topic

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

To check if your endpoint is publicly accessible, make a sample POST request from your local machine. For example:

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

If your endpoint is publicly accessible, then the command returns the following HTTP status code:

200 OK

If you're subscribing an HTTP 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 host name must not contain an underscore. For example, the following host name isn't permitted: your_hostname

Validate your endpoint response header

Complete the following steps based on the type of authentication that you're using: 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 should return the HTTP/1.1 401 Unauthorized header response along with a "WWW-Authenticate" header. The header value should contain the keyword "Basic" and other optional parameters supported in RFC 2617 (from the RFC Editor website). For example:

WWW-Authenticate: Basic

Digest access authentication:

When your endpoint receives an unauthenticated request, it should return an HTTP/1.1 401 Unauthorized header response along with a "WWW-Authenticate" header. The header value should contain the keyword "Digest," a randomly generated single-use value called a "nonce," an authentication realm, and other optional parameters supported in RFC 2617 (from the RFC Editor website). For example:

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

Set up delivery status logging

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 try to subscribe an HTTP(S) endpoint.

Failure logs, if any, will be generated in a log group in the following format:

sns/your_aws_region/your_account_ID/your_topic_name/Failure

Note: To see why your subscription confirmation notification failed delivery, check providerResponse in your Amazon CloudWatch delivery status logs.

Check the SSL certificate for your HTTPS endpoint

If you're using an HTTPS endpoint, 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 from the SSL Labs website.

Or, 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

If the SSL certificate returned by the endpoint isn't trusted or complete, then you could see the following providerResponse in your 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(S) endpoint

If a firewall is preventing the delivery of the SNS subscription confirmation notification to your HTTP(S) endpoints, allow the AWS Region specific IP addresses.

Check if your HTTP(S) endpoint has a subscription filter policy

If your endpoint is in a subscribed state but isn't receiving topic notifications, then complete the following steps:

1.    Check if your endpoint has a subscription filter policy configured. If your HTTP(S) subscription has a filter policy, notifications could be getting filtered.

2.    To confirm that your SNS messages are getting filtered, check the following CloudWatch metrics: NumberOfNotificationsFilteredOutNumberOfNotificationsFilteredOut-InvalidAttributes, and NumberOfNotificationsFilteredOut-NoMessageAttributes.


Did this article help?


Do you need billing or technical support?