Amazon SNS Notifications
The Amazon Simple Notification Service (Amazon SNS) is a managed service that provides message delivery from publishers to subscribers. Publishers communicate asynchronously with subscribers by sending messages to a topic, which is a logical access point and communication channel. Clients can subscribe to the SNS topic and receive published messages using a supported endpoint type, including:
- Amazon Kinesis Data Firehose
- Amazon SQS
- AWS Lambda
- HTTP
- Mobile push notifications
- Mobile text messages (SMS)
In the AFL API, there are 4 types of SNS notifications available:
- Match Status
- Score
- Metric Update
- Reference Data
In the sections below, there is a detailed breakdown of each message type with sample payloads and a list of the available items that you can expect to receive from each.
For further reading around AWS SNS please refer to the following AWS SNS documentation.
Subscribing to an SNS Topic
To receive messages published to an SNS topic, you must subscribe one of your endpoints to that topic. When you establish a subscribe via your endpoint to the topic, the endpoint begins to receive messages published to the associated topic.
To subscribe to a SNS topic you will need to determine which communication method you will implement.
LAMBDA
If you select Lambda as the subscription method, you will need to provide us your AWS account details so we can approve your connection. In addition, you will need to be provided with the arn of our SNS Topic that you will be subscribing to. This will be provided to you via your client manager during the initial engagement.
For more details on creating a Lambda subscription refer to the following AWS Lambda documentation.
HTTP(s)
To create a HTTP(s) subscription you will need to establish an endpoint at your end capable of receiving SNS messages and then provide us with the endpoint URL. We will then create the subscription in our systems.
For more details on creating a HTTP(s) subscription refer to the following AWS documentation:
Filtering your subscription
By applying optional filters to your subscription, you can choose which of the available message types listed below are published to you. In this way you may want to create multiple subscriptions, filtering by a type, which react to only that type of message.
For instance, if you filter a subscription by just the Score message type, you can then have a function that retrieves the most recent match scores from the API for the associated match. This is perfect for applications, or services where timely score displays are a must.
In this case you would simply apply the following Subscription filter:
{
"Type": "MATCH_STATUS",
}
https://api.afl.championdata.io
SNS Message Types
MATCH STATUS
This notification is triggered when the Match Status changes for a particular match. This notification allows the client to react to a match starting, entering a period break, and ending for instance.
A list of all possible values for “MatchStatus” in a Match Status message can be found from the following match status metadata endpoint: /v1/metadata/matchstatus. Note that it is the “code” values from this endpoint’s response that are used for the “Type” in the SNS message.
Here are some examples of messages:
{
"Records": [
{
"EventSource": "aws:sns",
"EventSubscriptionArn": "",
"EventVersion": "1.0",
"Sns": {
"Message": "{"MatchId":"233041024","Type":"Q1"}",
"MessageAttributes": {
"competitionId": {
"Type": "String",
"Value": "0"
},
"matchStatus": {
"Type": "String",
"Value": "Q1"
},
"seasonId": {
"Type": "String",
"Value": "2021"
},
"leagueId": {
"Type": "String",
"Value": "1"
},
"levelId": {
"Type": "String",
"Value": "14"
},
"phaseId": {
"Type": "String",
"Value": "11376"
},
"type": {
"Type": "String",
"Value": "MATCH_STATUS"
},
"matchId": {
"Type": "String",
"Value": "233041024"
}
},
"MessageId": "",
"Signature": "",
"SignatureVersion": "1",
"SigningCertUrl": "",
"Subject": null,
"Timestamp": "2023-12-13T06:30:10.454Z",
"TopicArn": "",
"Type": "Notification",
"UnsubscribeUrl": ""
}
}
]
}
{
"MatchStatus": "QT"
}
{
"MatchStatus": "FT"
}
{
"MatchStatus": "COMP"
}
SCORE
This notification is triggered when a team has scored in a particular match, which allows the client to retrieve the updated scores as soon as they are available.
{
"Records": [
{
"EventSource": "aws:sns",
"EventSubscriptionArn": "",
"EventVersion": "1.0",
"Sns": {
"Message": "{"MatchId":"232990753","Type":"SCORE","MetricsUpdated":null}",
"MessageAttributes": {
"competitionId": {
"Type": "String",
"Value": "0"
},
"matchStatus": {
"Type": "String",
"Value": "COMP"
},
"seasonId": {
"Type": "String",
"Value": "2021"
},
"leagueId": {
"Type": "String",
"Value": "2"
},
"levelId": {
"Type": "String",
"Value": "101"
},
"phaseId": {
"Type": "String",
"Value": "11375"
},
"type": {
"Type": "String",
"Value": "METRIC"
},
"matchId": {
"Type": "String",
"Value": "232990753"
}
},
"MessageId": "",
"Signature": "",
"SignatureVersion": "1",
"SigningCertUrl": "",
"Subject": null,
"Timestamp": "2023-12-13T07:08:35.764Z",
"TopicArn": "",
"Type": "Notification",
"UnsubscribeUrl": ""
}
}
]
}
METRIC UPDATE
This notification lists the most recent metrics that have been updated for a particular match, which allows a client to determine if they need to retrieve updated data from the API.
{
"Records": [
{
"EventSource": "aws:sns",
"EventSubscriptionArn": "",
"EventVersion": "1.0",
"Sns": {
"Message": "{"MatchId":"232990753","Type":"METRIC","MetricsUpdated":["KICK","TACKLE"]}",
"MessageAttributes": {
"competitionId": {
"Type": "String",
"Value": "0"
},
"matchStatus": {
"Type": "String",
"Value": "COMP"
},
"seasonId": {
"Type": "String",
"Value": "2021"
},
"leagueId": {
"Type": "String",
"Value": "2"
},
"levelId": {
"Type": "String",
"Value": "101"
},
"phaseId": {
"Type": "String",
"Value": "11375"
},
"metrics": {
"Type": "String",
"Value": "["KICK","TACKLE"]"
},
"type": {
"Type": "String",
"Value": "METRIC"
},
"matchId": {
"Type": "String",
"Value": "232990753"
}
},
"MessageId": "",
"Signature": "",
"SignatureVersion": "1",
"SigningCertUrl": "",
"Subject": null,
"Timestamp": "2023-12-13T07:08:35.764Z",
"TopicArn": "",
"Type": "Notification",
"UnsubscribeUrl": ""
}
}
]
}
REFERENCE DATA
This notification is triggered whenever Reference Data has been ingested, which allows clients to retrieve the most up to date reference data as soon as it is available.
{
"Records": [
{
"EventSource": "aws:sns",
"EventSubscriptionArn": "",
"EventVersion": "1.0",
"Sns": {
"Message": "{"Type":"REF_DATA"}",
"MessageAttributes": {
"type": {
"Type": "String",
"Value": "REF_DATA"
}
},
"MessageId": "",
"Signature": "",
"SignatureVersion": "1",
"SigningCertUrl": "",
"Subject": null,
"Timestamp": "2023-12-13T20:01:25.068Z",
"TopicArn": "",
"Type": "Notification",
"UnsubscribeUrl": ""
}
}
]
}