Receive user scores

There's a lot you can build with user scores. Go all out!

Our systems can send your users' scores to you in real-time. Our partners use scores for innovative use cases:

  • Create leaderboards, and organise tournaments on your platform

  • Give score targets to your users and reward them if they achieve scores

We can send user scores to you in 2 ways:

Via Webhooks

You can get scores of your users in real-time providing us a POST API / webhook URL. Gamezop will push your users' scores to this API.

In order for this to work, you must also append a sub query parameter to the game url received in the All Games API.

For example:

The value of this sub param must be a unique user identifier for the user playing the game. Max supported length of this value is 100 characters. Scores are always scoped to a game and user identifier.

Webhook to receive scores from Gamezop


Gamezop posts user scores in real-time to your webhook





We can add in an API Key in the headers for added authentication if you require us to.

We will send a JSON object to your webhook when users' scores update. The data body will contain the following fields:



Unique code assigned to each game - this is the code value received in the All Games API


Unique session identifier generated by Gamezop - remains same throughout a session


Unique game play identifier generated by Gamezop - remains same throughout a game play. There can be multiple game plays per session - each time the user loses the game, a new game play starts.


Unix timestamp - denotes the exact time at which this score was made by the user


Score made by the user



User identifier passed by you as sub parameter in the game URL


The ISO 3166-2 country code for the country from which the user is playing the game


Total time spent in the game play so until the point of the webhook call (captured in milliseconds). When a new game play starts, this is reset to 0.


Denotes the state of game at the time the score was made. It can be one of the following values:

  • loaded: score is always 0 with this state - it just means that the game finished loading.

  • start: This is fired at the start of every new game play. score and duration are 0 in this state update.

  • playing: This state means that the game is being played by the user - as the user's score keeps changing, we keep sending them to your API

  • over: The score received with this state value denotes the user's score when the game got over. Within the same session, a user can retry a game several times. This means that there may be several over states within the same session.

  • levelup: In case of level-based games, this state denotes the completion of a level.

Via client-side broadcasts

Client-side callbacks can also be made for these score updates.

This is usually needed if you wish to use them to trigger custom UI elements. We could add your JS tags to games, or make broadcasts over a WebView bridge.

Please contact your Gamezop Account Manager to enable client-side broadcasts.

Last updated