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 of IDs of entities of that type.
The Webhook Filter Entity API supports PlayHQ’s live game webhook solution; more information can be found here.
Play HQ API credentials
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.
As the filter API is a private endpoint, you will need to authenticate using the tenant (e.g. ca, nzc, afl), API client id key and secret as the first step. Please visit our Technical Documentation site for more information.
- In UAT, please authenticate with a POST request using the URL: https://api.uat.playhq.com/auth
- In PRODUCTION, please authenticate with a POST request using the URL: https://api.playhq.com/auth
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 APIs, described below, to add/delete/list IDs in the filter as required.
Common route parameters
All API routes in this document share the same base route:
|:subscriberId||The unique ID for your webhook subscriber. A subscriber represents the endpoint to which webhooks will be posted.|
|:subscriptionId||The unique ID representing a subscription to a particular domain of webhooks. A subscriber can have multiple subscriptions. For example if a subscriber wishes to receive grade create/updated/deleted webhooks, and live game webhooks, they will have two separate subscriptions, each with their own ID.|
The entity type by which a subscription's webhooks are filtered, for example PLAYING_SURFACE or GAME.
Since filters belong to subscriptions, not subscribers, a subscriber could choose to receive, for example, all grade webhooks (by having no filter on their grade webhook subscription), but only some live game (by having a filter on their live game webhook subscription).
Supported filters by webhook entity type
|Webhook Entity Type||Supported filters|
Lists the IDs currently present in the filter.
Example response body:
Adds a new ID to the filter. On success a 200 status code is returned, with an empty response body.
Deletes an ID from a filter. On success a 200 status code is returned, with an empty response body.
This operation is idempotent, so no error is returned if the entity ID is not present in the filter.
At this time there is no API for bulk adding or removing IDs in a filter. Multiple PUT/DELETE requests must be made, one for each ID.