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. Details of each type of supported event is below.

Each request also contains a X-TBA-Checksum header that you can use to validate requests on your client. The header will contain a hash of a secret key that you set when you create the webhook concatenated with the payload string. This is caculated using SHA1(secret+payload). 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!

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 enum of this file to see which types are enabled on the server.

Upcoming Match Notification

These notifications are tested for every three minutes. A notification will be sent for the next unplayed match of each currently live event.

Structure

  • message_type: “upcoming_match”
  • fields in “message_data” object
    • “match_key”
    • “event_name”
    • “team_keys”: list of keys for all teams participating in the match
    • “scheduled_time”: time that the match was originally scheduled for, in UNIX UTC
    • “predicted_time”: time that the match is predicted to start at based on the times that scores were posted for previous events, in UNIX UTC

Example JSON

            {"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"}
            

Test Notification

Send Test Upcoming Match

Match Score Notification

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

Structure

  • message_type: “match_score”
  • fields in “message_data” object
    • “event_name”
    • “match”: a full match model representing the appropriate 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

Send Test Match Score

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_type: “starting_comp_level”
  • fields in “message_data” object
    • “event_name”
    • “event_key”
    • “comp_level”: One of these types
    • “scheduled_time”: the time that the specified comp level is scheduled to start

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

Send Test Level Starting

Alliance Selection Notification

This notification is sent out every time the alliances at a live event are updated

Structure

  • message_type: “alliance_selection”
  • fields in “message_data” object
    • “event”: full event model for the related event

Example JSON

            {"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"}
            

Test Notification

Send Test Alliance Selection

Awards Posted Notification

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

Structure

  • message_type: “awards_posted”
  • fields in message_data object
    • “event_name”
    • “awards”: If we want awards for a specific team (if user is subscribed to the EventTeam), then this is an array of the following objects (else, it will be null)
      • “award_name”
      • “team_key”: Key of winning team
      • “team_name”: Name of winning team

Example JSON

            {"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"}
            

Test Notification

Send Test Awards

Team Media Posted Notification

This notification is sent out whenever new team media is posted (can be either photos or videos).

Structure

  • message_type: “media_posted”
  • fields in message_data object

Example JSON

            Not yet implemented
            

District Points Updated Notification

This notification is sent when points are recalculated for a district

Structure

  • message_type: “district_points_updated”
  • fields in message_data object
    • “district_key”
    • “district_name”

Example JSON

            Not yet implemented
            

Event Schedule Updated

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

Structure

  • message_type: “schedule_updated”
  • fields in message_data object
    • “event_key”
    • “event_name”
    • “first_match_time” (optional)

Example JSON

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

Test Notification

Send Test Schedule Update

Final Results Notification

This notification is sent upon the conclusion of a live event

Structure

  • message_type: “final_results”
  • fields in message_data object
    • “team_key”
    • “team_name”
    • “event_key”
    • “event_name”

Example JSON

            Not yet implemented
          

Ping Notification

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

Structure

  • "message_type": "ping"
  • fields in message_data object
    • "title": Title of the notification to be shown
    • "desc": Contents of the notification

Example JSON

            {"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"}
            

Admin Broadcast

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

Structure

  • "message_type: "broadcast"
  • fields in message_data object
    • "title": Title of the notification to be shown
    • "desc": Contents of the notification
    • "url": URL to open when the notification is tapped
    • "app_version": App version number this broadcast is targeting

Example JSON

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

Update Favorites Notification

This notification is sent out to a user's devices when favorites are updated on their account, telling that device to re-sync the list from the server.

Structure

  • "message_type": "update_favorites"

Example JSON

            {"message_type": "update_favorites"}
            

Update Subscriptions Notification

This notification is sent out to a user's devices when their subscriptions are updated for the account, telling that device to re-sync the list from the server.

Structure

  • "message_type": "update_subscriptions"

Example JSON

            {"message_type": "update_subscriptions"}
            

Webhook Verification Notifications

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_type": "verification"
  • fields in message_data object
    • "verification_key"

Example JSON

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