Webhook

PC and Mobile

Webhook Integration

Overview

When using the UserID & Webhook campaign type, game results are not displayed on an in-game leaderboard. Instead, the results are sent directly to your server via a webhook POST request.

This allows you to collect game data in real time and integrate it with your own system — whether that's a database, CRM, analytics platform, or even a simple Google Sheet.

---

How It Works

1. Your website embeds the game with a userid parameter

2. The user plays the game

3. Upon completion, our system sends the game result to your Webhook URL via POST

4. Your server processes the data and returns a status code

Your Website                          Branded Mini-Games
    |                                        |
    |-- userid (via URL parameter) --------->|
    |                                        |  User plays the game
    |<-- Webhook POST (game result) ---------|
    |                                        |
    |-- Return "S" (success) --------------->|

---

URL Parameter

Append the userid as a GET parameter when embedding the game:

https://branded.mini-games.io/?php=landing@game&campaign_no=YOUR_CAMPAIGN_NO&userid=T4g4fLTa

For details on generating and managing user IDs, see the User ID Setup Guide.

---

Webhook Data

The following parameters are sent to your Webhook URL via POST:

Parameter	Required	Description	Example
userid	Yes	Unique user identifier sent by your system	T4g4fLTa
tx_id	Yes	Unique transaction ID for each game play	234234
time	Yes	Date and time when the user played the game	2025-04-10 06:39:23
score	Yes	Score the user achieved	3500
playtime	Yes	Play duration in seconds	20

Data Format

You can choose the data format in the Studio settings:

• default — standard form POST (application/x-www-form-urlencoded)

• json — JSON format (application/json)

---

Return Code

Your webhook endpoint must return a status code to confirm receipt:

Code	Description
S	Successfully received and processed
F	Failed. You may include a reason, e.g., F: Score is missing.

---

Server-Side Example (Node.js)

app.post('/webhook', (req, res) => {
  const { userid, tx_id, time, score, playtime } = req.body;

  // Validate required fields
  if (!userid || !tx_id || !score) {
    return res.send('F: Missing required fields.');
  }

  // Store the data in your database
  db.insert({ userid, tx_id, time, score, playtime });

  return res.send('S');
});

---

Google Sheets Integration (No Server Required)

If you don't have a backend server, you can use Google Apps Script to receive webhook data directly into a Google Sheet. This is ideal for promotions, contests, or quick setups.

Step 1: Create a Google Sheet

1. Go to Google Sheets and create a new spreadsheet

2. In the first row, add headers:

A	B	C	D	E	F
Received	userid	tx_id	time	score	playtime

Step 2: Open Apps Script

1. In your Google Sheet, go to Extensions > Apps Script

2. Delete any existing code and paste the following:

function doPost(e) {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  var data = JSON.parse(e.postData.contents);

  sheet.appendRow([
    new Date(),
    data.userid,
    data.tx_id,
    data.time,
    data.score,
    data.playtime
  ]);

  return ContentService.createTextOutput('S');
}

1. Click Save (Ctrl+S / Cmd+S)

Step 3: Deploy as Web App

1. Click Deploy > New deployment

2. Click the gear icon and select Web app

3. Configure the settings:

Setting	Value
Description	Webhook receiver
Execute as	Me (your Google account)
Who has access	Anyone

1. Click Deploy

2. Authorize the app when prompted (review permissions and allow)

3. Copy the Web app URL — this is your Webhook URL

The URL looks like: https://script.google.com/macros/s/AKfycb.../exec

Step 4: Set the Webhook URL in Studio

1. Go to your campaign's UserID & Webhook settings

2. Paste the Web app URL into the Webhook URL field

3. Set Result data format to json

4. Click Update the URL information

Important Notes

• Result data format must be set to json — Google Apps Script's JSON.parse(e.postData.contents) expects JSON format. If set to default, the data will not be parsed correctly.

• Re-deploy after code changes — Every time you edit the Apps Script code, you must create a New deployment (not just save). The URL changes with each new deployment, so update the Webhook URL in Studio accordingly.

• Google account permissions — The script runs under your Google account. The first deployment requires authorization to access your Google Sheets.

• Rate limits — Google Apps Script has a daily quota (approximately 20,000 requests/day for free accounts). For high-traffic campaigns, consider a dedicated server instead.

• Response time — Apps Script may have a slight delay (1-3 seconds). This does not affect the game experience, as the webhook is sent asynchronously after the game ends.

• Data privacy — Game result data is stored in your Google Sheet. Ensure your spreadsheet sharing settings are appropriate for your data privacy requirements.

---

Testing Your Webhook

You can test your webhook endpoint using curl:

curl -X POST https://your-webhook-url \
  -H "Content-Type: application/json" \
  -d '{"userid":"testuser","tx_id":"123456","time":"2025-04-10 06:39:23","score":"3500","playtime":"20"}'

Expected response: S

---

Building a Leaderboard with Webhook Data

The webhook data you receive can be used to build your own leaderboard. Below are no-code and low-code options that receive scores and display rankings on your website.

---

Option 1: Zapier + KeepTheScore (Recommended)

Use Zapier to receive the webhook and push scores to KeepTheScore, which provides a hosted leaderboard with real-time updates.

Game End → Webhook POST → Zapier (receive) → KeepTheScore API (push score)
                                                      ↓
                                        Embed leaderboard on your website

Step 1: Create a Zap

1. Go to Zapier and create a new Zap

2. Trigger: Choose "Webhooks by Zapier" → "Catch Hook"

3. Copy the webhook URL provided by Zapier

4. Paste this URL into your campaign's Webhook URL field in Studio

5. Set Result data format to json

Step 2: Create a KeepTheScore Board

1. Go to keepthescore.com and create a new leaderboard

2. Note your board ID from the URL (e.g., https://keepthescore.com/board/xxxxxx/)

3. Get your API key from the board settings

Step 3: Connect Zapier to KeepTheScore

1. Action: Choose "Webhooks by Zapier" → "POST"

2. URL: https://keepthescore.com/api/xxxxxx/score/

3. Payload Type: json

4. Data: Map userid → player name, score → score value

Step 4: Embed on Your Website

<iframe src="https://keepthescore.com/board/xxxxxx/leaderboard/"
        width="100%" height="600" frameborder="0"></iframe>

Feature	Details
Real-time updates	Scores appear automatically
Filters	All-time, daily, weekly, monthly
Pricing	Basic free, premium features paid
WordPress	WP plugin available (shortcode embed)

---

Option 2: Airtable (Webhook + Data Management + Embed)

Airtable can receive webhooks directly, store data, and embed a sorted view as a leaderboard.

Step 1: Create a Base

Create an Airtable base with these fields:

Field	Type
userid	Single line text
score	Number
tx_id	Single line text
time	Date
playtime	Number

Step 2: Set Up Webhook Automation

1. Go to Automations → Create automation

2. Trigger: When webhook received

3. Copy the webhook URL and paste it into Studio's Webhook URL field

4. Action: Create record — map the webhook fields to your table columns

Step 3: Create a Leaderboard View

1. Create a new Grid view named "Leaderboard"

2. Sort by score descending

3. Hide unnecessary columns (tx_id, playtime, etc.)

Step 4: Embed on Your Website

1. Click Share and sync → Embed this view

2. Copy the iframe code

Feature	Details
Webhook	Built-in, no middleware needed
Data management	Filter, search, export
Pricing	Free (1,000 records), Team $20/user/month
Limitation	Embed uses Airtable's default styling

---

Option 3: Google Sheets + Common Ninja Widget

Combine the Google Sheets integration above with Common Ninja's Leaderboard Widget for a visual leaderboard.

Step 1: Set up Google Sheets webhook receiver (see above)

Step 2: Create a Common Ninja leaderboard widget

1. Go to commoninja.com/widgets/leaderboard

2. Create a new widget and configure the API Integration to read from your Google Sheet

3. Customize the design (colors, layout, number of entries)

Step 3: Embed the widget on your website

<!-- Common Ninja embed code (from widget settings) -->
<div class="commoninja_component" comp-type="leaderboard" comp-id="YOUR_WIDGET_ID"></div>
<script src="https://cdn.commoninja.com/sdk/latest/commonninja.js"></script>

Feature	Details
Design	Highly customizable
Data source	Google Sheets, Airtable, or API
WordPress	WP plugin available
Pricing	Free tier available

---

Option 4: Leaderboarded

Leaderboarded.com — dedicated leaderboard SaaS with API and WordPress support.

Feature	Details
API	REST API for pushing scores
Themes	40+ leaderboard themes
Embed	iframe, real-time updates
WordPress	WP shortcode embed
Pricing	Free tier, embed requires Business plan

---

Which Option Should I Choose?

	Zapier + KeepTheScore	Airtable	Sheets + Common Ninja	Leaderboarded
Easiest setup	Good	Best	Moderate	Good
Leaderboard design	Good (themes)	Basic	Best (customizable)	Good (40+ themes)
Data management	Limited	Best	Good (Sheets)	Limited
No middleware needed	No (Zapier)	Yes	No (Apps Script)	No (Zapier/Make)
WordPress plugin	Yes	No	Yes	Yes
Best for	Quick leaderboard	Data + leaderboard	Custom design	Themed boards