Webhook Filter Entity API

Overview

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.

Terms of use

https://www.playhq.com/terms

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. 

When the filters are set up they will appear in the top level of the subscribed webhooks payloads. Here is a sample of what a webhook payload looks like with filters;

"messageId": "12d5f1f1-49ea-422c-bfb0-33a8eb3f2e38",
"eventType": "LIVE_GAME.DETAIL_UPDATED",
"entityId": "dd5cdf44-3fa3-4885-bc7f-79edade26124",
"eventRaisedDateTime": "2022-06-29T19:26:22.546Z",
"filters": [
{
"entityType": "PLAYING_SURFACE",
"entityId": "204ac60d-e19d-43af-83c5-041145db72a0
}
],
"data": {...

The filter array is designed to be used in collaboration with the filter API and will populate depending on what filters your subscriber has set up. If you have chosen to subscribe to games at a particular playing surface then all related game webhook events will contain the playing surface id. 

Configuration

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. 

Resources

Common route parameters

All API routes in this document share the same base route:

/partner/v1/webhooks/subscribers/:subscriberId/subscriptions/:subscriptionId/filters/:entityType

Supported filters by webhook entity type

List

GET
/partner/v1/webhooks/subscribers/:subscriberId/subscriptions/:subscriptionId/filters/:entityType/ids

Lists the IDs currently present in the filter.

Example response body:

{
 "ids":
[ 
"952a73fa-cef1-4571-b2d6-2504cc8b75ee", 
"225d9b8e-e890-4452-ba23-207b735bf911"
 ]
}

Create

PUT
/partner/v1/webhooks/subscribers/:subscriberId/subscriptions/:subscriptionId/filters/:entityType/ids/:entityId