Live Scoreboard Integration

Applicable to: Sport and Integration Partners
Application: PlayHQ API's

This article will cover the following:

1. How the live scoreboard integration works
2. Process for scoreboard providers to integrate with PlayHQ
3. What are the live scoring webhook events and their triggers
4. How webhook filtering works
5. PlayHQ fee to integrate

Related articles:

• Webhook Filter Entity API
• Live Game Webhook Events - Sample Data
• How To E-Score Cricket
• How To Use PlayHQ API's

Resources:

• PlayHQ Technical Documentation

Overview

Using PlayHQ’s live game webhook solution, integration partners (including scoreboard providers) can display game scores and other relevant game information in real-time, while a game is being live scored on PlayHQ’s electronic scoring system.

This article describes the key events in a game as told by PlayHQ’s live game webhook solution and aims to assist integration partners to integrate with these webhooks.

Getting started with the live scoreboard integration

This integration relies on an integration partner to consume webhook events that are pushed to a specified site, a http link/URL. These events will be triggered in real-time capturing relevant updates.

For your development and testing purposes, PlayHQ can set you up with access to a relevant test environment. This will require you to kindly provide a test URI that we can send the webhook events to.

We can also provide you with a means to scope/filter these events via API so that you only receive webhooks for the games that you are interested in, please refer to Using Webhook Filtering below for more information.

To express interest in becoming an integration partner, please reach out using our Sales & Partnerships form on the Contact Us page. 

Live scoring webhook events

Integration partners will be subscribed to six webhook events, documentation linked below;

• Live Game Detail Updated - Pushes toss and/or lineup updates during a live scored game from PlayHQ’s electronic scoring platform. This will always be the first live game webhook event and will also be sent at the start of each subsequent innings or whenever lineup changes. 
• Live Game Scorecard - Provides the full scorecard of the game and current batter/bowler selections, during a live scored game from PlayHQ’s electronic scoring platform. The scorecard webhook is triggered at the end of each over, whenever a new batter or bowler is selected, start/end/split of each innings, whenever penalty runs are applied, when a player is retired out not out and at the removal of a score event. 
• Live Game Score Event - Captures information about each ball/score event as well as current progress scores for the teams and players involved in the score event. For example batter 123 was caught by fielder 456 and here is now the updated score of the game and the individuals batting & bowling as at the event. 
• Live Game Undo Event - This webhook captures undo or deletion of a ball/score event, during a live scored game from PlayHQ’s electronic scoring platform. 
• Live Game Reset - This webhook provides game reset updates, which clears the game of any previously captured scores and starts the game from the beginning again, while scoring a game from PlayHQ’s electronic scoring platform. 
• Game Summary Webhook - Captures real time updates pre and post game including participant & team line up information, statistics and schedule. This webhook does NOT provide live score updates.

Triggering webhook events

The game summary webhook event is typically triggered by:

• updates made by an association to the game details (i.e. venue allocate, date, time) 
• team line-ups added by clubs or associations pre game via the Admin Portal or My Teams

The live game webhook events will be triggered only while scoring a game from PlayHQ’s electronic scoring platform. 

Using webhook filtering

An integration partner may only wish to receive a subset of all webhooks. For example;

• A fixed scoreboard operator only needs live game webhooks for games played at locations where they operate a scoreboard. 
• A mobile scoreboard operator only needs live game webhooks for games to which they have arranged to deploy one of their mobile scoreboards. 

To facilitate this, a webhook subscription can be set up with an entity filter. An entity filter is an entity type (e.g. playing surface or game), plus a list IDs of entities of that type. For example; 

• A fixed scoreboard operator would use a filter of type PLAYING_SURFACE, with a list of IDs of the playing surfaces at which they have installed scoreboards. This list wouldn’t change very often - just occasionally adding a new ID whenever they install a new scoreboard. 
• A mobile scoreboard operator would use a filter of type GAME, with a list of IDs of games for which they have arranged to deployed their scoreboards. A mobile scoreboard operator would be regularly adding new upcoming game IDs to this list. 

A webhook will only be dispatched to a subscriber if it passes the subscriber's entity filter. For example when determining whether the fixed scoreboard operator should receive a given live game event webhook, our dispatcher will check the playing surface that the game is being played at, and will only dispatch the webhook to that the playing surface ID appears in the subscriber’s PLAYING_SURFACE filter. Similarly the mobile scoreboard operator will only receive a live game webhook if the game ID appears in their GAME filter. 

Configuration

Filters, just like subscribers and subscriptions, are set up by PlayHQ upon request. When it is first created, the filter’s entity type is set, but the list of IDs is empty.

This means that, initially, the subscriber would receive no webhooks at all.

It is then up to the integration partner to use the Webhook Filter Entity API. More information on the Webhook Filter Entity API can be found here.