# Leaderboard Webhooks

After each game, <mark style="color:red;">InHouseQueue</mark> can POST your leaderboard data to a Webhook URL of your choice. If you have a website or an API integration, you can use this to build a custom leaderboard.

## :crown: Webhook URL

```
/premium webook_url (url) (delete)
```

### To receive the webhook we send, you'll need the following:

1. **A Web Server with a Public URL:**
   * You need a website or server that is accessible online. This could be a website you own or a cloud server you set up.
2. **Create a POST Endpoint:**
   * Set up a specific URL on your server (e.g., `https://yourwebsite.com/webhook`) that can accept POST requests. This is where <mark style="color:red;">InHouseQueue</mark> will send the data.
3. **Handle Incoming JSON Data:**
   * Configure your endpoint to receive and process the JSON data that <mark style="color:red;">InHouseQueue</mark> sends after each game. This usually involves writing some code to parse the JSON and use the information as needed.
4. **Check the Webhook-Secret header**
   * To ensure InHouseQueue is sending you the webhook, we advise you check `Webhook-Secret` header. You can compare this header value to the secret we share with you.
5. **Test Your Endpoint:**
   * Make sure your endpoint is working correctly by sending test POST requests. You can use tools like [Postman](https://www.postman.com/) to simulate the webhook and verify that your server receives and handles the data properly.

### JSON sent by InHouseQueue (No Active seasons)

In most cases, the JSON payload will look like this.

{% hint style="warning" %}
**To receive the `mmr` parameter please ensure your leaderboard order it set to MMR. For more information please visit** [**here**](https://docs.inhousequeue.xyz/docs/commands/leaderboard-commands#change-the-order-of-leaderboard-crown)
{% endhint %}

{% tabs %}
{% tab title="200" %}

```json
{
  "game": "lol",
  "leaderboard": {
     "is_unique": false,
     "sorted_by": "MMR",
     "leaderboard_channel_id": 1234567890,
     "mmr_type": "dynamic",
     "player_entries": [
        {
          "name": "__snipy__",
          "most_played_role": {"name": "top", "frequency": 999},
          "position": 1,
          "wins": 99,
          "losses": 99,
          "total_games": 198,
          "win_rate_percentage": 50,
          "mmr": 9999
        },
        // other players data
     ]
  }
}
```

{% endtab %}
{% endtabs %}

### JSON sent by InHouseQueue (Active Season)

If you have a [season ](https://docs.inhousequeue.xyz/docs/inhousequeue-seasons#how-to-setup-seasons)running the `season` object is included in the payload.

{% hint style="warning" %}
**To receive the `mmr` parameter please ensure your leaderboard order it set to MMR. For more information please visit** [**here**](https://docs.inhousequeue.xyz/docs/commands/leaderboard-commands#change-the-order-of-leaderboard-crown)
{% endhint %}

{% tabs %}
{% tab title="200" %}

```json
{
  "game": "lol",
  "season": {
    "name": "A season name",
    "number": 10
  },
  "leaderboard": {
     "is_unique": false,
     "sorted_by": "MMR",
     "leaderboard_channel_id": 1234567890,
     "mmr_type": "dynamic",
     "player_entries": [
        {
          "name": "__snipy__",
          "most_played_role": {"name": "top", "frequency": 999},
          "position": 1,
          "wins": 99,
          "losses": 99,
          "total_games": 198,
          "win_rate_percentage": 50,
          "mmr": 9999
        },
        // other players data
     ]
  }
}
```

{% endtab %}
{% endtabs %}

## Headers & Webhook verification

Here are the basic headers we send.

```
content-length	492
user-agent	Python/3.11 aiohttp/3.10.5
accept-encoding	gzip, deflate
webhook-secret	<your_secret>
content-type	application/json
```

For your own security, please verify the `webhook-secret` header on every request to ensure the data is really from InHouseQueue. You will receive the secret via an ephemeral message (visible only to you) after running `/premium webook_url (url) (delete)`. This is not required but we recommend it.

When your endpoint receives a request, compare the `webhook-secret` header to the secret value we provided. If they don't match, reject the request.

If your token is ever compromised, simply re-run `/premium webook_url (url) (delete)` to regenerate a new secret token.

We cannot give you your secret token after the ephemeral message expires. So please keep it safe.

**Top-Level Fields**

| **Field**     | **Type** | **Description**                       | Optional |
| ------------- | -------- | ------------------------------------- | -------- |
| `game`        | `string` | The game identifier (e.g., `"lol"`).  | No       |
| `seasons`     | `object` | Information about the current season. | Yes      |
| `leaderboard` | `object` | Contains all leaderboard details.     | No       |

**`season` Object**

***

| **Field Path**  | **Type**  | **Description**                                           |
| --------------- | --------- | --------------------------------------------------------- |
| `season.name`   | `string`  | The name of the current season (e.g., `"A season name"`). |
| `season.number` | `integer` | The number identifier of the season (e.g., `10`).         |

**`leaderboard` Object**

***

<table data-header-hidden><thead><tr><th width="266"></th><th width="138"></th><th></th></tr></thead><tbody><tr><td><strong>Field</strong></td><td><strong>Type</strong></td><td><strong>Description</strong></td></tr><tr><td><code>is_unique</code></td><td><code>boolean</code></td><td>Indicates if the leaderboard is unique. More information <a href="../quick-start/leaderboards-explained">here</a></td></tr><tr><td><code>sorted_by</code></td><td><code>string</code></td><td>How the leaderboard is sorted. It can be MMR or WINS</td></tr><tr><td><code>leaderboard_channel_id</code></td><td><code>integer</code></td><td>Discord channel ID for the leaderboard.</td></tr><tr><td><code>mmr_type</code></td><td><code>string</code></td><td>The MMR system in use. Either <code>"dynamic"</code> or <code>"flat"</code>. Useful when the <code>mmr</code> field is present, as flat and dynamic MMR values are not directly comparable.</td></tr><tr><td><code>player_entries</code></td><td><code>array</code> of <code>object</code></td><td>List of players in the leaderboard.</td></tr></tbody></table>

**`player_entries` Array Items**

***

<table data-header-hidden><thead><tr><th width="313"></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Field</strong></td><td><strong>Type</strong></td><td><strong>Description</strong></td></tr><tr><td><code>name</code></td><td><code>string</code></td><td>Player's in-game name (e.g., <code>"__snipy__"</code>).</td></tr><tr><td><code>most_played_role</code></td><td><code>object</code></td><td>The player's most played role. <strong>OPTIONAL:</strong> This object will <strong>NOT</strong> appear if you are playing "custom" game.</td></tr><tr><td><code>most_played_role.name</code></td><td><code>string</code></td><td>Name of the role (e.g., <code>"top"</code>).</td></tr><tr><td><code>most_played_role.frequency</code></td><td><code>integer</code></td><td>Number of times the role was played (e.g., <code>999</code>).</td></tr><tr><td><code>position</code></td><td><code>integer</code></td><td>Player's position in the leaderboard. <strong>Note:</strong> Positions are zero-indexed, so first place is <code>0</code>, second place is <code>1</code>, and so on.</td></tr><tr><td><code>wins</code></td><td><code>integer</code></td><td>Number of wins the player has (e.g., <code>99</code>).</td></tr><tr><td><code>losses</code></td><td><code>integer</code></td><td>Number of losses the player has (e.g., <code>99</code>).</td></tr><tr><td><code>total_games</code></td><td><code>integer</code></td><td>Total games played by the player (e.g., <code>198</code>).</td></tr><tr><td><code>win_rate_percentage</code></td><td><code>integer</code></td><td>Player's win rate percentage (e.g., <code>50</code>).</td></tr><tr><td><code>mmr</code></td><td><code>integer</code></td><td>Player's MMR for this leaderboard. (e.g., <code>1000</code>) - <strong>Note:</strong> This is NOT included if your <code>sorted_by</code> is WINS.</td></tr></tbody></table>