# 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**](/docs/commands/leaderboard-commands.md#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 ](/docs/features/inhousequeue-seasons.md#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**](/docs/commands/leaderboard-commands.md#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="/pages/EM0CmutIXEZGZgGaN8vP">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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.inhousequeue.xyz/docs/features/leaderboard-webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.