🪅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

{
  "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": "[e-mail]",
      "points": [
        {
          "tokenId": "661e8410fdd48f6a010c2c61",
          "tokenName": "test token 3",
          "amount": 945
        }
      ],
      "updatedAt": "2024-05-23T23:23:48.078Z"
    }
  }
}

Event: item.created

{
  "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:

{
  "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"
    }
  }
}