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. 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 enum of this file to see which types are enabled on the server.
These notifications are tested for every two minutes. A notification will be sent for the next unplayed match of each currently live event.
{"message_data": {"event_name": "New England FRC Region Championship", "scheduled_time": 1397330280, "match_key": "2014necmp_f1m1", "team_keys": ["frc195", "frc558", "frc5122", "frc177", "frc230", "frc4055"], "predicted_time": 1397330280}, "message_type": "upcoming_match"}
This notification is sent every time a match score at a live event is updated.
{"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 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_data": {"event_name": "New England FRC Region Championship", "comp_level": "f", "event_key": "2014necmp", "scheduled_time": 1397330280}, "message_type": "starting_comp_level"}
This notification is sent out every time the alliances at a live event are updated
{"message_data": {"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_data": {"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 out whenever new team media is posted (can be either photos or videos).
Not yet implemented
This notification is sent when points are recalculated for a district
{"message_data": {"district_key": "2014ne", "district_name": "New England"}, "message_type": "district_points_updated"}
This notification is sent when new unplayed matches are added to a live event.
{"message_data": {"event_name": "New England FRC Region Championship", "first_match_time": 1397330280, "event_key": "2014necmp"}, "message_type": "schedule_updated"}
This notification is sent upon the conclusion of a live event
Not yet implemented
This notification is sent from the Account Overview page to an individual one of the user's connected devices.
{"message_data": {"desc": "This is a test message ensuring your device can recieve push messages from The Blue Alliance.", "title": "Test Message"}, "message_type": "ping"}
This notification can be sent by TBA Admins when they want to announce something important.
{"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_data": {"verification_key": "8279a61abdeee0cf46a86136bf888188a4b18cdf"}, "message_type": "verification"}
