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.
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.
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.
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.
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.
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.
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.
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.
Message Key: upcoming_match
| 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. |
{"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"}
This notification is sent every time a match score at a live event is updated.
Message Key: match_score
| 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. |
{"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"}
This notification is sent every time a match video is added to a match.
Message Key: match_video
| 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. |
{"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"}
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.
Message Key: starting_comp_level
| 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 |
{"message_data": {"event_name": "New England FRC Region Championship", "comp_level": "f", "event_key": "2014necmp", "scheduled_time": 1397330280}, "message_type": "starting_comp_level"}
These notifications are posted after alliance selection results have been posted for the event.
Message Key: alliance_selection
| 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. |
{"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"}
This notification is sent every time an award is added at a live event
Message Key: awards_posted
| 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. |
{"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"}
This notification is sent when new unplayed matches are added to a live event.
Message Key: schedule_updated
| 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 |
{"message_data": {"event_key": "2014necmp", "event_name": "New England FRC Region Championship", "first_match_time": 1397330280}, "message_type": "schedule_updated"}
This notification is sent from the Account Overview page to an individual one of the user's connected devices.
Message Key: ping
| Key | Description | Examples |
|---|---|---|
title |
Test Notification | |
desc |
This is a test message ensuring your device can recieve push messages from The Blue Alliance. |
{"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"}
This notification can be sent by TBA Admins when they want to announce something important.
Message Key: broadcast
| 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 |
{"message_data": {"title": "Test", "desc": "Test Broadcast", "url": "http://foo.bar"}, "message_type": "broadcast"}
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.
Message Key: verification
| Key | Description | Examples |
|---|---|---|
verification_key |
The SHA1 verification key for the webhook | 8279a61abdeee0cf46a86136bf888188a4b18cdf |
{"message_data": {"verification_key": "8279a61abdeee0cf46a86136bf888188a4b18cdf"}, "message_type": "verification"}
