Webhooks - syd711/vpin-studio GitHub Wiki

The VPin Studio server allows 3rd party integrations by using webhooks. This page shows which webhook events are available and how you can register them.

Webhook Events

The list below shows the endpoint webhooks can be registered for. Note that currently only unauthorized HTTP calls are provided.

Endpoint	Event	Request Method	Description
Highscores	UPDATE	PUT	If a highscore is updated, a registered webhook is called with a PUT request and an "id" parameter which contains the game id of the updated score.
Games	CREATE	POST	If a game is imported to the frontend, a registered webhook is called with a POST request and an "id" parameter which contains the id of the new game.
Games	UPDATE	PUT	If a game is updated, a registered webhook is called with a PUT request and an "id" parameter which contains the game id of the updated game.
Games	DELETE	DELETE	If a game is deleted, a registered webhook is called with a DELETE request and an "id" parameter which is appended as URL segment to the registered webhook URL.
Players	CREATE	POST	If a player is created, a registered webhook is called with a POST request and an "id" parameter which contains the id of the new player.
Players	UPDATE	PUT	If a player is updated, a registered webhook is called with a POST request and an "id" parameter which contains the id of the player.
Players	DELETE	DELETE	If a player is deleted, a registered webhook is called with a DELETE request and an "id" parameter which is appended as URL segment to the registered webhook URL.

Webhook Registration (UI)

Webhooks can be registered via the UI by opening the corresponding preferences. Note that the webhook sets passed via REST API are also shown here.

The preference manage different sets of webhooks, including the optional static parameters.

Webhook Registration (Programmatically)

In addition to the manual setup, webhooks can also be registered via a REST call to the Studio server. The example below shows an example of the JSON that needs to be passed to the REST endpoint

http://HOST:8089/api/v1/webhooks

via a POST call:

{
    "name": "my webhooks",
    "uuid": "1234567890",
    "enabled": true,
    "scores": {
        "endpoint": "http://localhost:8080/webhook/addScore",
        "parameters": {
            "roomID": 1, 
            "customKey": "customValue"
        },
        "subscribe": ["update"]
    },
    "games": {
        "endpoint": "http://localhost:8080/webhook/games",
        "parameters": {
            "roomID": 1,
            "gameCategory": "arcade"
        },
        "subscribe": ["update", "delete", "create"]
    },
    "players": {
        "endpoint": "http://localhost:8080/webhook/players",
        "parameters": {
            "playerGroup": "VIP"
        },
        "subscribe": ["update", "delete", "create"]
    }
} 

You can delete webhooks using a DELETE request with the given URL and the UUID of the set to delete: http://HOST:8089/api/v1/webhooks/{uuid}

Field Details

Field(s)	Description
name	The name of the webhook set, select a meaningful name here since the result is also editable in the UI.
uuid	The unique id of the webhook. If a set with the given id exists, it will be overwritten.
endpoint	The webhook URL to be called
parameters	An optional map of fix parameters. This will be passed to all PUT and POST requests.
subscribe	The possible event types to register the webhook for: update, delete and create

Note that the highscore webhook is only called for update events.

Public API Endpoints

Since only ids are passed to the webhooks, these need a "return call" to retrieve the actual data. The list below shows the endpoints that can be used to retrieve the actual data for the events that have been fired.

URL	Request Method	Description	Status
http://localhost:8089/api/v1/games	GET	Gets the list of all games registered at the frontend.	TBD: payload too large
http://localhost:8089/api/v1/games/{id}	GET	Gets the game with the given id.	TBD: playload too large
http://localhost:8089/api/v1/players	GET	Gets the list of all players.
http://localhost:8089/api/v1/players/{id}	GET	Gets the player with the given id.
http://localhost:8089/api/v1/games/scores/{id}	GET	Gets the latest highscore for the game with the given id.