Webhooks

Overview

This documentation is for using webhooks with The Blue Alliance's dataset, which allow our server to push notifications to you, but only when the data is updated. Notifications will be sent as HTTP POST requests to a URL that your specify. This API does not replace the regular API; it should be used to replace excessive polling or in other situations where realtime notifications are beneficial.

Request Structure

Each request will contain a payload of JSON data containing information about the event that has been pushed to you. Each request will contain a message_type and message_data field. The message_type field can be used to determine the data being sent. The message_data is the data specific to the message being sent. Details of each type of supported event is below.

Each request also contains a X-TBA-HMAC header that you can use to validate requests on your client. The header will contain a hash of a secret key that is set by the server when you create the webhook concatenated with the payload string. This is caculated using NIST's HMAC algorithm, using SHA256. You can see in the code where this is calculated.

Configuration

Webhooks are tied to your TBA Account - you can create them from your account overview. You will have to enter a URL that will receive the pushed notification. You also have to enter a secret key used to secure requests - we recommend using a long randomly generated string. When you receive a webhook, TBA will send a HTTP POST request to the URL you have entered, so make sure you're listening. Not responding or returning an error code may cause your webhook to be deleted.

Validation

Once you create a webhook from the web interface, The Blue Alliance will push an initial notification to your server. The message will be of type 'verification' and look something like this: {"message_type": "verification", "message_data": {"verification_key": "a93774ec6197d456f4aaadfea5fdba6697e71e6a"}} Once you receive a verification message, go to your account overview, where you can verify the webhook you just created. If you need to, you can resend a new verification code (keep in mind that only the most recently sent code will properly verify a webhook). Until you have verified your webhook, it will not recieve any notifications from The Blue Alliance. You can still ping a webhook from the account panel without verification in order to make sure it's working properly - but no other notifications will go through. So be sure to verify your webhooks soon after making them!

We will periodically prune non-responsive webhooks by checking if a webhook responds to a ping request with a 200 status code. Your webhook should handle responding to a ping to ensure it does not get pruned.

Testing

If you want to test out recieving webhooks on your local computer, you can use a program called ngrok to expose a port on your device to the internet. You can check out this page from GitHub's documentation to see a brief overview of testing webhooks using ngrok. There is a small example script with some instructions here.

Additionally, each notification type that is enabled will have a section for "testing" where you can send a static instance of that notification type to all of your devices. This feature will use the account you currently have logged in, and send it to every device registered with that account. Every event referenced will be 2014necmp and every match will be 2014necmp_f1m1.

The Firehose

If you want your webhook to recieve updates for every event in a year, you can subscribe to the TBA Notification Firehose. On the myTBA Page for your account, go to the Subscriptions tab. At the bottom of the page, you can subscribe to all events in this year. Choose the notification types you would like to be updated for, and submit. Keep in mind that this subscription is only good for one season - if you want to continue receiving updates next season, you will have to subscribe again. Beware: subscribing to the firsthose will also send every notification to all your connected mobile devices. We recommend you not subscribe to the Firehose using an account that is also connected to your phone, unless you want a constant stream of notifications, there as well.

You can see an example App Engine site that is subscribed to the Firehose, stores all the incoming data in the ndb, and displays it here.

Notification Types

Please keep in mind that not all notification types have been implemented or enabled yet. Watch the ENABLED_NOTIFICATIONS dictionary of this file to see which types are enabled on the server.

Upcoming Match Notification

These notifications are after scores have been posted for match N - 2. In the case of a match schedule first being released or matches between days (ex: the first match on the second day of an event), this notification will be sent ~7m before the start of the match.

Structure

Message Key: upcoming_match

message_data Fields
Key Description Examples
event_key TBA API key for the Event the Match will be played at 2014necmp
match_key TBA API key for the Match 2014necmp_f1m1
team_key (Optional) TBA API key for the Team. Will only be included if the upcoming match notification is being sent for a Team subscription. frc7332
event_name Official name of event on record either provided by FIRST or organizers of offseason event New England FRC Region Championship
team_keys List of TBA API Team keys for all teams participating in the match frc195, frc558, ...
scheduled_time (Optional) Time that the match was originally scheduled for, in UNIX UTC. Will not be included if the match does not have a scheduled start time 1397330280
predicted_time (Optional) Time that the match is predicted to start at based on the times that scores were posted for previous events, in UNIX UTC. Will not be included if the match start time cannot be predicted 1397330280
webcast (Optional) A TBA API Webcast object for the Event. Only one webcast will be sent, regardless of how many webcasts the Event has. Will only include webcasts that have been determined to be "online". Will not be included if there are no online webcats for the event.

Example JSON

          {"message_data": {"event_key": "2014necmp", "match_key": "2014necmp_f1m1", "event_name": "New England FRC Region Championship", "team_keys": ["frc195", "frc558", "frc5122", "frc177", "frc230", "frc4055"], "scheduled_time": 1397330280, "predicted_time": 1397330280, "webcast": {"type": "twitch", "channel": "nefirst_blue"}}, "message_type": "upcoming_match"}
          

Test Notification

Match Score Notification

This notification is sent every time a match score at a live event is updated.

Structure

Message Key: match_score

message_data Fields
Key Description Examples
event_key TBA API key for the Event the Match will be played at 2014necmp
match_key TBA API key for the Match 2014necmp_f1m1
team_key (Optional) TBA API key for the Team. Will only be included if the upcoming match notification is being sent for a Team subscription. frc7332
event_name Official name of event on record either provided by FIRST or organizers of offseason event New England FRC Region Championship
match A TBA API Match object for the match.

Example JSON

          {"message_data": {"event_name": "New England FRC Region Championship", "match": {"comp_level": "f", "match_number": 1, "videos": [], "time_string": "3:18 PM", "set_number": 1, "key": "2014necmp_f1m1", "time": 1397330280, "score_breakdown": null, "alliances": {"blue": {"score": 154, "teams": ["frc177", "frc230", "frc4055"]}, "red": {"score": 78, "teams": ["frc195", "frc558", "frc5122"]} }, "event_key": "2014necmp"} }, "message_type": "match_score"}
          

Test Notification

Match Video Notification

This notification is sent every time a match video is added to a match.

Structure

Message Key: match_video

message_data Fields
Key Description Examples
event_key TBA API key for the Event the Match was played at 2014necmp
match_key TBA API key for the Match 2014necmp_f1m1
team_key (Optional) TBA API key for the Team. Will only be included if the upcoming match notification is being sent for a Team subscription. frc7332
event_name Official name of event on record either provided by FIRST or organizers of offseason event New England FRC Region Championship
match A TBA API Match object for the match.

Example JSON

          {"message_data": {"event_name": "New England FRC Region Championship", "match": {"comp_level": "f", "match_number": 1, "videos": [{"key": "ZrDxXDC1y5I", "type": "youtube"}], "time_string": "3:18 PM", "set_number": 1, "key": "2014necmp_f1m1", "time": 1397330280, "score_breakdown": null, "event_key": "2014necmp"} }, "message_type": "match_video"}
          

Test Notification

Competition Level Starting Notification

This notification is sent at the same time as Upcoming Match Notifications are. If the next upcoming match is of a different type (qual, quarterfinal, semifinal, etc.), then this notification will also be sent out.

Structure

Message Key: starting_comp_level

message_data Fields
Key Description Examples
event_key TBA API key for the Event the Match will be played at 2014necmp
event_name Official name of event on record either provided by FIRST or organizers of offseason event New England FRC Region Championship
comp_level One of these strings representing the competition level that is starting qf
scheduled_time (Optional) Time that the first match of the comp level was originally scheduled for, in UNIX UTC. Will not be included if the match does not have a scheduled start time 1397330280

Example JSON

            {"message_data": {"event_name": "New England FRC Region Championship", "comp_level": "f", "event_key": "2014necmp", "scheduled_time": 1397330280}, "message_type": "starting_comp_level"}
            

Test Notification

Alliance Selection Notification

These notifications are posted after alliance selection results have been posted for the event.

Structure

Message Key: alliance_selection

message_data Fields
Key Description Examples
event_key TBA API key for the Event the alliance selection results were posted at 2014necmp
team_key (Optional) TBA API key for the Team. Will only be included if the upcoming match notification is being sent for a Team subscription. frc7332
event_name Official name of event on record either provided by FIRST or organizers of offseason event New England FRC Region Championship
event A TBA API Event object for the event.

Example JSON

            {"message_data": {"event_name": "New England FRC Region Championship", "event_key": "2014necmp", "event": {"key": "2014necmp", "website": "http://www.nefirst.org/", "official": true, "end_date": "2014-04-12", "name": "New England FRC Region Championship", "short_name": "New England", "facebook_eid": null, "event_district_string": "New England", "venue_address": "Boston University\nAgganis Arena\nBoston, MA 02215\nUSA", "event_district": 3, "location": "Boston, MA, USA", "event_code": "necmp", "year": 2014, "webcast": [], "alliances": [{"declines": [], "picks": ["frc195", "frc558", "frc5122"]}, {"declines": [], "picks": ["frc1153", "frc125", "frc4048"]}, {"declines": [], "picks": ["frc230", "frc177", "frc4055"]}, {"declines": [], "picks": ["frc716", "frc78", "frc811"]}, {"declines": [], "picks": ["frc1519", "frc3467", "frc58"]}, {"declines": [], "picks": ["frc131", "frc175", "frc1073"]}, {"declines": [], "picks": ["frc228", "frc3525", "frc2168"]}, {"declines": [], "picks": ["frc172", "frc1058", "frc2067"]}], "event_type_string": "District Championship", "start_date": "2014-04-10", "event_type": 2} }, "message_type": "alliance_selection"}
            

Test Notification

Awards Posted Notification

This notification is sent every time an award is added at a live event

Structure

Message Key: awards_posted

message_data Fields
Key Description Examples
event_key TBA API key for the Event the alliance selection results were posted at 2014necmp
team_key (Optional) TBA API key for the Team. Will only be included if the upcoming match notification is being sent for a Team subscription. frc7332
event_name Official name of event on record either provided by FIRST or organizers of offseason event New England FRC Region Championship
awards A list of TBA API Award objects that are being awarded. In the case of an Event subscription, all awards for the event will be sent. In the case of a Team subscription, only awards won by the team will be sent.

Example JSON

            {"message_data": {"event_key": "2014necmp", "event_name": "New England FRC Region Championship", "awards": [{"event_key": "2014necmp", "award_type": 0, "name": "Regional Chairman's Award", "recipient_list": [{"team_number": 2067, "awardee": null}, {"team_number": 78, "awardee": null}, {"team_number": 811, "awardee": null}, {"team_number": 2648, "awardee": null}], "year": 2014}]}, "message_type": "awards_posted"}
            

Test Notification

Event Schedule Updated

This notification is sent when new unplayed matches are added to a live event.

Structure

Message Key: schedule_updated

message_data Fields
Key Description Examples
event_key TBA API key for the Event the alliance selection results were posted at 2014necmp
event_name Official name of event on record either provided by FIRST or organizers of offseason event New England FRC Region Championship
first_match_time (Optional) Time that the next unplayed match for the event is scheduled for, in UNIX UTC. Will not be included if the match does not have a scheduled start time 1397330280

Example JSON

            {"message_data": {"event_key": "2014necmp", "event_name": "New England FRC Region Championship", "first_match_time": 1397330280}, "message_type": "schedule_updated"}
            

Test Notification

Ping Notification

This notification is sent from the Account Overview page to an individual one of the user's connected devices.

Structure

Message Key: ping

message_data Fields
Key Description Examples
title Test Notification
desc This is a test message ensuring your device can recieve push messages from The Blue Alliance.

Example JSON

            {"message_data": {"title": "Test Message", "desc": "This is a test message ensuring your device can recieve push messages from The Blue Alliance."}, "message_type": "ping"}
            

Broadcast

This notification can be sent by TBA Admins when they want to announce something important.

Structure

Message Key: broadcast

message_data Fields
Key Description Examples
title Title of the notification to be shown Test
desc Contents of the notification Test Broadcast
url (Optional) A URL with additional information http://foo.bar

Example JSON

            {"message_data": {"title": "Test", "desc": "Test Broadcast", "url": "http://foo.bar"}, "message_type": "broadcast"}
            

Verification

This notification is sent when a new webhook is created. It contains a verification code that needs to be entered in the Account Overview page for the webhook before it recieves live updates.

Structure

Message Key: verification

message_data Fields
Key Description Examples
verification_key The SHA1 verification key for the webhook 8279a61abdeee0cf46a86136bf888188a4b18cdf

Example JSON

              {"message_data": {"verification_key": "8279a61abdeee0cf46a86136bf888188a4b18cdf"}, "message_type": "verification"}