Push Overview

The Insights Push feed is a webhook-based, real-time feed that automatically sends new insights to you upon generation. It ensures reliable and efficient delivery of the most up-to-date insights and can dramatically reduce the number of calls you need to make to our RESTful Insights V2 API.

The structure and content (JSON payload) of insights delivered by the push feed are identical to the RESTful API. However, how you choose which insights to receive differs from the Insights V2 API. You can subscribe to topics defined simply by league, insightType, and locale.

Getting Started

To subscribe to the Insights Push feed, you will need to:

Set up a public web server that is configured to receive POST requests

Your web server must not require any authentication on POST requests
Make sure your web server is not configured with a firewall to block incoming requests

Send us the HTTPS endpoint where this web server is exposed, and a label you would like to reference this URL by (e.g. "prod", "dev")
Send us the topics (combinations of league, insightType, and locale) you would like this endpoint subscribed to.

Parameters

Parameter	Description
`league`	Desired league for insights `mlb`, `nba`, `ncaamb`, `nfl`, `ncaafb`, `nhl`
`insightType`	Desired type of insight `expert_picks`, `highs`, `leaderboards`, `lineup_changes`, `milestones`, `player_betting_trends`, `predictions`, `scoring`, `team_betting_trends`
`locale`	2 letter code for supported languages `en` (English), `fr`(French), `de`(German), `it`(Italian), `es`(Spanish) Note: Non-English translations are currently only available for Scoring insights

Your endpoint must quickly return a 2xx response prior to any complex logic that could cause a timeout. If your endpoint goes offline and/or does not return a 2xx response upon receiving an insight, the Push feed will attempt to redeliver the insight to your webhook endpoint with an exponential back off.

Subscription Confirmation

Subscription Confirmation Sample

{
  "Type": "SubscriptionConfirmation",
  "MessageId": "d0776612-6cd1-49ba-a0bc-0d26e137ae02",
  "Token": "2336412f37fb687f5d51e6e2425c464cefc600f65e7b3825a843e9722e219fc5b8cda4086488540df281cbf79edc7c2d03be9e38e11d7ce064fd8fc24cd43bd49d9375754c89432c3ac132fbdb80194b7e71a57d3ae6f6e1f34704cf51bfd72ceaad93543553466e88244f31d84d73bfe44c8e2e0a9ba72d143aabb883783868420c244a4c2c61d4dc016c3778b0bc578b0322a8f4db60ca5cb274cd25e16428",
  "TopicArn": "arn:aws:sns:us-east-1:038785188916:radar360-push-prod-NflMilestonesPushTopic-AtgiU177X7KK",
  "Message": "You have chosen to subscribe to the topic arn:aws:sns:us-east-1:038785188916:radar360-push-prod-NflMilestonesPushTopic-AtgiU177X7KK.\nTo confirm the subscription, visit the SubscribeURL included in this message.",
  "SubscribeURL": "https://sns.us-east-1.amazonaws.com/?Action=ConfirmSubscription&TopicArn=arn:aws:sns:us-east-1:038785188916:radar360-push-prod-NflMilestonesPushTopic-AtgiU177X7KK&Token=2336412f37fb687f5d51e6e2425c464cefc600f65e7b3825a843e9722e219fc5b8cda4086488540df281cbf79edc7c2d03be9e38e11d7ce064fd8fc24cd43bd49d9375754c89432c3ac132fbdb80194b7e71a57d3ae6f6e1f34704cf51bfd72ceaad93543553466e88244f31d84d73bfe44c8e2e0a9ba72d143aabb883783868420c244a4c2c61d4dc016c3778b0bc578b0322a8f4db60ca5cb274cd25e16428",
  "Timestamp": "2023-10-24T16:55:27.813Z",
  "SignatureVersion": "1",
  "Signature": "Wh8w6/DXUu+4F9cQ8KWN0bMEj9Jyi2lK1VdkS7WWpO+NbEpMEpsuqX4d85rFWlvHscR+K0r5iZ2ox4E1y0FBqz44FMZeEQeZ5W0G7+ZOiewnjIdQzBjXps3T/zmGNxMWXHoJiyDJ04T/lGTSzMJ+h71ak/mvuX2uBbH+gv+f/tMXvD4k48bWfLTygO7plh3hKRniOXWJK82yxc9O9liZaSndCKTwkPcYeFLvS/TmdeFye6Is9fu+HreDpFCRom6iakMGXIee1ZrSRRiV0VxHz8KRMzCTyzKRjSxHNE8SQ32964KDg8I0LTybzX2N5YUDicyJAZImGuAY3g1wjITXDA==",
  "SigningCertURL": "https://sns.us-east-1.amazonaws.com/SimpleNotificationService-01d088a6f77103d0fe307c0069e40ed6.pem"
}

Upon being subscribed to a topic, a confirmation POST request will be made to your endpoint. You must confirm each subscription by visiting (sending a GET request to) the SubscribeURL from the request body in order to start receiving insights for that topic.

We recommend that you configure your client to automatically send a GET request to this address upon receiving a subscription confirmation so that you do not encounter disruptions if we need to resubscribe your endpoint, or if you choose to have your subscriptions modified in the future.

Click here for a subscription confirmation example.

Each message (with the exception of subscription confirmations) is signed with a private key that we share with you so that you can verify insights as originating from Sportradar. Specifically, we have implemented SHA256 HMAC signatures decoded as hex on a combination of the timestamp and insight, like so:

const signedPayload = `${timestamp}.${JSON.stringify(event.insight)}`
const computedSignature = crypto.createHmac('sha256', SECRET_KEY).update(signedPayload).digest('hex')

See below for sample implementation.

Implementation

You should expose a POST endpoint to receive insights at, confirm subscription requests, and perform signature validation.

Click here for an example implementation of a client which consumes our push feed in Javascript using Node.js and Express.