AWS SNS endpoint

You can create AWS SNS HTTPS endpoints to trigger Notify17 notifications.

Notify17 has SNS-specialized APIs, which will automatically confirm your SNS subscription and accept your SNS messages.

The conceptual diagram

Raw notifications

You can use AWS SNS to trigger a raw notification, by using the following URL as an SNS endpoint, for the desired raw API keys:

https://hook.notify17.net/api/raw/{RAW_API_KEY}/sns

For this scenario, Notify17 behavior will be:

  • The Subject of the SNS message becomes the title of the Notify17 notification. If no subject is provided, the notification title will default to:

    SNS message [sns-topic-name]
    
  • The Message of the SNS message becomes the body of the Notify17 notification.

  • Other attributes, like silent, sound, etc, can be set using Message Attributes of type String, e.g:

    • To generate a notification with a specific sound, create a String message attribute, with key sound and the desired sound name (e.g. doink) as value.

    • To generate a silent notification, create a String message attribute, with key silent and true as value.

    • In general, the behavior for decoding message attributes is:

      1. Try to decode the attribute value as if it was a JSON value, e.g. true => true (boolean), "hello" => hello (string).
      2. If the decoding does not work, treat the value as a string.

Templated notifications

You can use AWS SNS to trigger a templated notification, by using the following URL as an SNS endpoint, for the desired template API keys:

https://hook.notify17.net/api/template/{TEMPLATE_API_KEY}/sns

For this scenario, Notify17 behavior will be:

  • The Subject of the SNS message is available in the Subject variable.

  • The Message of the SNS message is available in the Message variable.

  • All other Message Attributes are available under the attributesMap variable (in a “compact” format), and under the MessageAttributes variable (in the standard SNS format).

    E.g. a custom attribute instanceName’s value will become available at .attributesMap.instanceName and .MessageAttributes.instanceName.Value.

  • All SNS attributes in general will be available under their respective names, e.g. .TopicArn.

Catch-all template

You can import and save the following generic catch-all template in your Notify17 account:

Template Payload (YAML)
{{ 
  default
    (
      printf 
      "SNS message - %s" 
      (last (splitList ":" .TopicArn))
    ) 
    .Subject 
}}

---

{{ if isJson .Message }}
{{/* Decode the message and dump its content */}}

{{ dump (parseJson .Message) }}

{{ else }}
{{/* This is a normal text message */}}

{{ .Message }}

{{ if .attributesMap }}
{{/* If we have any attributes, let's show them */}}
Attributes: {{ dump .attributesMap | nindent 2 }}
{{ end }}

{{ end }}
Message: Hello there!
MessageAttributes:
  name:
    Type: String
    Value: General Kenobi
MessageId: 88302c8d-9d71-514c-bbb8-746c487fde28
Subject: Greetings!
Timestamp: 2021-04-26T03:01:02.694Z
TopicArn: arn:aws:sns:us-east-1:123:test-sns-template
attributesMap:
  name: General Kenobi
Rendered
Greetings!

---

Hello there!

Attributes: 
  name: General Kenobi

Raw templated notifications

You can use AWS SNS to trigger a raw templated notification, by using the following URL as an SNS endpoint, for the desired raw API keys:

https://hook.notify17.net/api/rawTemplated/{RAW_API_KEY}/sns

For this scenario, Notify17 behavior will be:

  • The notification templates need to be defined in the Message Attributes list, as String elements, e.g:

    Key: __n17TitleTemplate
    Value: Hello {{ .name }}
    
  • The Subject of the SNS message is available in the Subject variable.

  • The Message of the SNS message is available in the Message variable.

  • All other Message Attributes are available under the attributesMap variable (in a “compact” format), and under the MessageAttributes variable (in the standard SNS format).

    E.g. a custom attribute instanceName’s value will become available at .attributesMap.instanceName and .MessageAttributes.instanceName.Value.

  • All SNS attributes in general will be available under their respective names, e.g. .TopicArn.

SNS attributes

The default list of available SNS attributes for every SNS message is:

Attribute nameDescription
SubjectThe subject of the SNS message
MessageThe SNS message
MessageIdThe SNS message id
TimestampThe timestamp of the SNS message, e.g 2021-04-25T18:20:04.207Z
TopicArnThe ARN of the AWS SNS topic used to generate this notification, e.g. arn:aws:sns:us-east-1:123456789012:my-sns-topic
MessageAttributesThe original map of message attributes, in the standard SNS format
attributesMapThe map of message attributes, in a condensed key/value format

Example:

Subject: Hello!
Message: My message!
MessageId: aa059ca3-319d-5514-be36-c46cf0478666
Timestamp: 2021-04-25T19:14:23.661Z
TopicArn: arn:aws:sns:us-east-1:123456789012:my-sns-topic
MessageAttributes:
  myName:
    Type: String
    Value: Mr. Anderson
attributesMap:
  myName: Mr. Anderson