### Example JSON for Ping Notification Source: https://www.thebluealliance.com/apidocs/webhooks An example JSON payload for a `ping` notification, demonstrating a test message with a title and description. ```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"} ``` -------------------------------- ### Example JSON for Broadcast Notification Source: https://www.thebluealliance.com/apidocs/webhooks An example JSON payload for a `broadcast` notification, showing a test message with a title, description, and an optional URL. ```JSON {"message_data": {"title": "Test", "desc": "Test Broadcast", "url": "http://foo.bar"}, "message_type": "broadcast"} ``` -------------------------------- ### Example JSON for Event Schedule Updated Notification Source: https://www.thebluealliance.com/apidocs/webhooks An example JSON payload for a `schedule_updated` notification, including event key, name, and the first match time. ```JSON {"message_data": {"event_key": "2014necmp", "event_name": "New England FRC Region Championship", "first_match_time": 1397330280}, "message_type": "schedule_updated"} ``` -------------------------------- ### Example JSON Payload for Upcoming Match Notification Source: https://www.thebluealliance.com/apidocs/webhooks An example JSON payload demonstrating the structure and typical values for an `upcoming_match` notification, including event, match, team, time, and webcast details. ```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"} ``` -------------------------------- ### The Blue Alliance Webhook Verification Message Example Source: https://www.thebluealliance.com/apidocs/webhooks An example of the `verification` message type sent by The Blue Alliance to a newly configured webhook URL. This message is crucial for the initial verification process to activate the webhook. ```APIDOC { "message_type": "verification", "message_data": { "verification_key": "a93774ec6197d456f4aaadfea5fdba6697e71e6a" } } ``` -------------------------------- ### Example Webhook Verification JSON Payload Source: https://www.thebluealliance.com/apidocs/webhooks An example JSON payload demonstrating the structure of a webhook verification notification. This payload includes the `message_data` object with a sample `verification_key` and specifies the `message_type` as `verification`. ```JSON {"message_data": {"verification_key": "8279a61abdeee0cf46a86136bf888188a4b18cdf"}, "message_type": "verification"} ``` -------------------------------- ### Example JSON for Alliance Selection Notification Source: https://www.thebluealliance.com/apidocs/webhooks An example JSON payload representing an `alliance_selection` notification from The Blue Alliance API. It includes detailed event information such as name, key, dates, location, and webcasts. ```JSON {"message_data": {"event_name": "New England FRC Region Championship", "event_key": "2014necmp", "event": {"address": "Boston, MA 02215, USA", "city": "Boston", "country": "USA", "district": {"abbreviation": "ne", "display_name": "New England", "key": "2014ne", "year": 2014}, "division_keys": [], "end_date": "2014-04-12", "event_code": "necmp", "event_type": 2, "event_type_string": "District Championship", "first_event_code": "necmp", "first_event_id": "10871", "gmaps_place_id": "ChIJFzjlY_B544kRyL6j4ABuNCs", "gmaps_url": "https://maps.google.com/?cid=3113234192467738312", "key": "2014necmp", "lat": 42.3504997, "lng": -71.1053991, "location_name": "Boston University", "name": "New England FRC Region Championship", "parent_event_key": null, "playoff_type": null, "playoff_type_string": null, "postal_code": "02215", "short_name": "New England", "start_date": "2014-04-10", "state_prov": "MA", "timezone": "America/New_York", "webcasts": [{"channel": "7031031", "file": "2797186", "type": "livestream"}, {"channel": "7234441", "file": "2797207", "type": "livestream"}], "website": "http://www.nefirst.org/", "week": 6, "year": 2014}}, "message_type": "alliance_selection"} ``` -------------------------------- ### Example JSON for Awards Posted Notification Source: https://www.thebluealliance.com/apidocs/webhooks An example JSON payload for an `awards_posted` notification, showing an event with a 'Regional Chairman's Award' and its recipients. ```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"} ``` -------------------------------- ### Competition Level Starting Notification API Documentation Source: https://www.thebluealliance.com/apidocs/webhooks This notification is sent when a new competition level (e.g., quarterfinal, semifinal) is starting, typically alongside upcoming match notifications. It provides the event key, event name, competition level, and an optional scheduled time. ```APIDOC Message Key: starting_comp_level message_data Fields: event_key: TBA API key for the Event the Match will be played at (Example: 2014necmp) event_name: Official name of event on record either provided by *FIRST* or organizers of offseason event (Example: New England FRC Region Championship) comp_level: One of [these strings](https://github.com/the-blue-alliance/the-blue-alliance/blob/py3/src/backend/common/consts/comp_level.py#L6-L11) representing the competition level that is starting (Example: 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 (Example: 1397330280) ``` ```json {"message_data": {"event_name": "New England FRC Region Championship", "comp_level": "f", "event_key": "2014necmp", "scheduled_time": 1397330280}, "message_type": "starting_comp_level"} ``` -------------------------------- ### Match Score Notification API Documentation Source: https://www.thebluealliance.com/apidocs/webhooks This section details the structure and example JSON payload for the `match_score` notification, which provides real-time updates on match scores. It includes fields like event and match keys, team key (optional), event name, and a full Match object. ```APIDOC Message Key: match_score message_data Fields: event_key: TBA API key for the Event the Match will be played at (Example: 2014necmp) match_key: TBA API key for the Match (Example: 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. (Example: frc7332) event_name: Official name of event on record either provided by *FIRST* or organizers of offseason event (Example: New England FRC Region Championship) match: A TBA API [Match](/apidocs/v3#model-Match) object for the match. ``` ```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"} ``` -------------------------------- ### Upcoming Match Notification API Structure Source: https://www.thebluealliance.com/apidocs/webhooks Defines the structure of the `upcoming_match` notification, detailing the `message_data` fields, their types, and descriptions. This notification is sent before a match starts, providing details about the event, match, participating teams, and scheduled/predicted times. ```APIDOC Notification: upcoming_match message_data: Object event_key: string - TBA API key for the Event the Match will be played at (e.g., 2014necmp) match_key: string - TBA API key for the Match (e.g., 2014necmp_f1m1) team_key: string (Optional) - TBA API key for the Team. Will only be included if the upcoming match notification is being sent for a Team subscription. (e.g., frc7332) event_name: string - Official name of event on record either provided by *FIRST* or organizers of offseason event (e.g., New England FRC Region Championship) team_keys: array - List of TBA API Team keys for all teams participating in the match (e.g., frc195, frc558, ...) scheduled_time: number (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 (e.g., 1397330280) predicted_time: number (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 (e.g., 1397330280) webcast: Webcast Object (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. type: string channel: string message_type: string - Always "upcoming_match" ``` -------------------------------- ### Match Video Notification API Documentation Source: https://www.thebluealliance.com/apidocs/webhooks This notification is sent every time a match video is added to a match. It includes details such as event and match keys, team key (optional), event name, and a Match object with video information. ```APIDOC Message Key: match_video message_data Fields: event_key: TBA API key for the Event the Match was played at (Example: 2014necmp) match_key: TBA API key for the Match (Example: 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. (Example: frc7332) event_name: Official name of event on record either provided by *FIRST* or organizers of offseason event (Example: New England FRC Region Championship) match: A TBA API [Match](/apidocs/v3#model-Match) object for the match. ``` ```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"} ``` -------------------------------- ### Ping Notification API Documentation Source: https://www.thebluealliance.com/apidocs/webhooks Documentation for the `ping` notification, used to send a test message to an individual one of the user's connected devices from the Account Overview page. It defines the message key and fields for `title` and `desc`. ```APIDOC 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. | ``` -------------------------------- ### The Blue Alliance Read API v3 Authentication Source: https://www.thebluealliance.com/apidocs/index Authentication for The Blue Alliance Read API v3 requires an access token, which can be generated from your Account Dashboard. This token must be included with each request by passing it in the `X-TBA-Auth-Key` header or as a URL parameter. ```APIDOC Authentication Header: Name: X-TBA-Auth-Key Value: YOUR_ACCESS_TOKEN Location: Header or URL Parameter Note: Generate token from Account Dashboard ``` -------------------------------- ### Event Schedule Updated Notification API Documentation Source: https://www.thebluealliance.com/apidocs/webhooks Documentation for the `schedule_updated` notification, sent when new unplayed matches are added to a live event. It specifies the message key and fields such as `event_key`, `event_name`, and an optional `first_match_time` in UNIX UTC. ```APIDOC 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 | ``` -------------------------------- ### Broadcast Notification API Documentation Source: https://www.thebluealliance.com/apidocs/webhooks Documentation for the `broadcast` notification, which can be sent by TBA Admins when they want to announce something important. It specifies the message key and fields for `title`, `desc`, and an optional `url`. ```APIDOC 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 | ``` -------------------------------- ### Webhook Verification Notification Structure (APIDOC) Source: https://www.thebluealliance.com/apidocs/webhooks Defines the structure of the `verification` message type for The Blue Alliance API webhooks. It specifies the message key and the fields contained within the `message_data` payload, particularly the `verification_key` which is a SHA1 hash required for webhook activation. ```APIDOC Webhook Verification Notification: Message Key: verification message_data Fields: verification_key: Type: string (SHA1 hash) Description: The SHA1 verification key for the webhook Example: 8279a61abdeee0cf46a86136bf888188a4b18cdf ``` -------------------------------- ### Alliance Selection Notification API Documentation Source: https://www.thebluealliance.com/apidocs/webhooks These notifications are posted after alliance selection results have been published for an event. It includes the event key, an optional team key, event name, and a full Event object. ```APIDOC Message Key: alliance_selection message_data Fields: event_key: TBA API key for the Event the alliance selection results were posted at (Example: 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. (Example: frc7332) event_name: Official name of event on record either provided by *FIRST* or organizers of offseason event (Example: New England FRC Region Championship) event: A TBA API [Event](/apidocs/v3#model-Event) object for the event. ``` -------------------------------- ### The Blue Alliance Read API v3 Base URL Source: https://www.thebluealliance.com/apidocs/index All requests to The Blue Alliance Read API v3 should be made to this base URL. This is the primary endpoint for accessing data such as event listings, team information, and match results. ```APIDOC Base URL: https://www.thebluealliance.com/api/v3 ``` -------------------------------- ### Awards Posted Notification API Documentation Source: https://www.thebluealliance.com/apidocs/webhooks Documentation for the `awards_posted` notification, sent every time an award is added at a live event. It details the message key, required fields like `event_key`, `event_name`, and a list of `Award` objects, with an optional `team_key`. ```APIDOC 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](/apidocs/v3#model-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. | | ``` -------------------------------- ### The Blue Alliance Webhook Request Structure and Validation Source: https://www.thebluealliance.com/apidocs/webhooks Details the common structure of all webhook POST requests from The Blue Alliance, including the required JSON payload fields `message_type` and `message_data`, and the `X-TBA-HMAC` header used for validating the request's authenticity via HMAC-SHA256. ```APIDOC Webhook Request: Method: POST Content-Type: application/json Timeout: 10s (from TBA servers) Headers: X-TBA-HMAC: string Description: HMAC-SHA256 hash of (secret_key + payload_string) Purpose: Client-side request validation Body (JSON Payload): message_type: string Description: Identifies the type of event being pushed (e.g., "verification", "upcoming_match"). message_data: object Description: Contains data specific to the 'message_type'. ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.