> For the complete documentation index, see [llms.txt](https://docs.tryludo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryludo.com/gaming-getting-started/getting-set-up-with-custom-integration/webhook-integration-and-data-handling.md).

# Webhook Integration and Data Handling

Ludo's webhook feature allows integration with your systems to track player activities, update game data, and sync in-game assets. This document provides a step-by-step guide to setting up a webhook.

### 1. Setting Up the Webhook

1. **Navigate to the Integrations Section**
   * In the Ludo system, go to **Integrations** and select **Game Sync**.
2. **Create a Webhook**
   * Click on **Create Webhook** and input the **POST** endpoint where Ludo will send data.
   * Ensure that the endpoint is properly configured to receive and process the following event types.

### **2. Webhook Payload Structure**

In general, the body of a webhook contains the following parameters:

| **Parameter**   | **Data Type** | **Description**                                                                   |
| --------------- | ------------- | --------------------------------------------------------------------------------- |
| **id**          | String        | Unique identifier for the event.                                                  |
| **createdAt**   | String (ISO)  | Timestamp indicating when the event was created (e.g., "2024-06-26T00:31:24Z").   |
| **type**        | String        | The type of webhook event (e.g., `player.points.updated`, `item.created`).        |
| **data**        | Object        | Contains details about the event, including specific data objects.                |
| **environment** | String        | Specifies the environment where the transaction was processed (`test` or `live`). |

***

### **3. Data Object Structure**

The `data` object contains details relevant to the specific event. Its structure varies depending on the event type.

**Common Fields in the `data` Object:**

| **Parameter** | **Data Type** | **Description** |
| ------------- | ------------- | --------------- |

| **object** | Object | Contains specific details of the event (e.g., player details, points, or items). |
| ---------- | ------ | -------------------------------------------------------------------------------- |

| **ludoPlayerId** | String | Unique identifier for the Ludo player. |
| ---------------- | ------ | -------------------------------------- |

| **playerId** | String | Identifier used in your system to match the player. |
| ------------ | ------ | --------------------------------------------------- |

| **discordUserId** | String | Discord ID of the player, if applicable. |
| ----------------- | ------ | ---------------------------------------- |

| **telegramUserId** | String | Telegram ID of the player, if applicable. |
| ------------------ | ------ | ----------------------------------------- |

| **email** | String | Email associated with the player’s Ludo account. |
| --------- | ------ | ------------------------------------------------ |

| **name** | String | Name of the player. |
| -------- | ------ | ------------------- |

| **points** | Array of Objects | Details of the player’s point balances. Each object contains: |
| ---------- | ---------------- | ------------------------------------------------------------- |

| - **tokenId** | String | Unique identifier for the points token. |
| ------------- | ------ | --------------------------------------- |

| - **tokenName** | String | Name of the token (e.g., "Gold Points"). |
| --------------- | ------ | ---------------------------------------- |

| - **amount** | Integer | Total amount of points the player has for this token. |
| ------------ | ------- | ----------------------------------------------------- |

| **items** | Array of Objects | Details of items owned by the player. Each object contains: |
| --------- | ---------------- | ----------------------------------------------------------- |

| - **itemId** | String | Unique identifier for the item. |
| ------------ | ------ | ------------------------------- |

| - **productId** | String | Identifier linking the item to a specific product. |
| --------------- | ------ | -------------------------------------------------- |

| - **name** | String | Name of the item (e.g., "Golden Sword"). |
| ---------- | ------ | ---------------------------------------- |

| - **description** | String | Description of the item. |
| ----------------- | ------ | ------------------------ |

| - **imageUrl** | String (URL) | Link to the item’s image. |
| -------------- | ------------ | ------------------------- |

| - **createdAt** | String (ISO) | Timestamp when the item was created. |
| --------------- | ------------ | ------------------------------------ |

| **products** | Array of Objects | Details of products owned by the player. Each object contains: |
| ------------ | ---------------- | -------------------------------------------------------------- |

| - **productId** | String | Unique identifier for the product. |
| --------------- | ------ | ---------------------------------- |

| - **name** | String | Name of the product. |
| ---------- | ------ | -------------------- |

| - **description** | String | Description of the product. |
| ----------------- | ------ | --------------------------- |

| - **price** | Integer | Price of the product in points. |
| ----------- | ------- | ------------------------------- |

| - **createdAt** | String (ISO) | Timestamp when the product was created. |
| --------------- | ------------ | --------------------------------------- |

| **updatedAt** | String (ISO) | Timestamp of the last update to the player's data. |
| ------------- | ------------ | -------------------------------------------------- |

| **createdAt** | String (ISO) | Timestamp of when the player was first added to the system. |
| ------------- | ------------ | ----------------------------------------------------------- |

| **environment** | String | Specifies the environment where the transaction was processed (`test` or `live`). |
| --------------- | ------ | --------------------------------------------------------------------------------- |

### **4. Supported Event Types**

| **Category** | **Event Type**        | **Description**                               |
| ------------ | --------------------- | --------------------------------------------- |
| **Players**  | player.points.updated | Triggered when a player's points are updated. |
|              | player.items.updated  | Triggered when a player gains/loses an item.  |
| **Items**    | item.created          | Triggered when a new item is created.         |
|              | item.updated          | Triggered when an item is edited.             |
| **Products** | product.created       | Triggered when a product is created.          |
|              | product.updated       | Triggered when a product is updated.          |

### 5. Naming Convention for Events:

The event names follow this pattern:

`{category}.{event}.{sub-event}`

Example:

* `player.points.updated`
* `player.items.updated`

### 6. Example Events:

**player.points.updated**

```json
{
  "id": "evt_1MqqbKLt4dXK03v5qaIbiNCC",
  "createdAt": "2024-06-26T00:31:24.943Z",
  "type": "player.points.updated",
  "data": {
    "object": {
      "ludoPlayerId": "663cdb2eef2d1015b27c3d9a",
      "playerId": "game-player-2435",
      "name": "Renee Russo",
      "discordUserId": "634482720692502569",
      "email": "renee@ludo.com",
      "points": [
        {
          "tokenId": "661e8410fdd48f6a010c2c61",
          "tokenName": "test token 3",
          "amount": 945
        }
      ],
      "updatedAt": "2024-05-23T23:23:48.078Z"
    }
  }
}
```

**Event: item.created**

```json
{
  "id": "evt_2JjpbKLt8dYK03v5oaKbiXXY",
  "createdAt": "2024-06-26T01:15:45.125Z",
  "type": "item.created",
  "environment": "test",
  "data": {
    "object": {
      "itemId": "test-item-1",
      "name": "Golden Sword",
      "description": "A rare item for the ultimate warrior.",
      "imageUrl": "https://example.com/images/golden-sword.png",
      "createdAt": "2024-06-26T01:15:45.125Z"
    }
  }
}
```

### 7. How to Display Items per Player in the Game

Ludo will send player-related data, including points, products, and items, via webhooks. To show these items for each player in your game, follow these steps:

1. **Receive Webhook Data**:
   * When Ludo sends a webhook with the relevant data (e.g., `player.items.updated`), your system should process the webhook and update the player’s items.
2. **Update Player Items**:
   * Ensure that you update the **playerId** and **items** in your system with the new data received from the webhook.
   * This will allow your players to see the updated in-game assets in real-time.
3. **Sync with Player IDs**:
   * The data sent by Ludo contains the `playerId`, which should match the ID in your system, allowing for seamless integration and real-time updates of player items and points.

#### Example Event for Updating Player Items:

```json
{
  "id": "evt_1MqqbKLt4dXK03v5qaIbiNCC",
  "createdAt": "2024-06-26T00:31:24.943Z",
  "type": "player.items.updated",
  "data": {
    "object": {
      "playerId": "game-player-2435",
      "items": [
        {
          "itemId": "6627c5a06af08fc4225fecee",
          "productId": "6627c33b132f6a0e401467ed",
          "createdAt": "2024-05-16T19:41:11.126Z"
        }
      ],
      "updatedAt": "2024-05-23T23:23:48.078Z"
    }
  }
}
```