Webhook

A Webhook delivers a GAMEMONITORING event to your system immediately after an action on the platform. It is a regular POST request with a JSON body, so your website, panel, or game service can react automatically.

For vote rewards, complete this setup first, then use the dedicated flow: Vote rewards.

Connection

This setup links a GAMEMONITORING project to your handler and provides a signing token for verifying incoming requests.

  1. Open My projects, create a project or choose an existing one, then go to Webhook settings.
  2. Create a public HTTPS endpoint that accepts POST with Content-Type: application/json and does not redirect.
  3. In Webhook settings, enter the full handler URL, for example https://panel.example.com/gamemonitoring-webhook, and save it.
  4. Copy the signing token from the same block and add it to your handler script.
  5. In the handler, verify signature, process the required event_type, and return a successful 2xx response only after the event has been processed.

After setup, send a test Webhook from the interface and check the delivery status. For the example URL, your server must accept POST on /gamemonitoring-webhook.

If the test fails, use the handler response as the first clue: 401 means a signature problem, 403 or an HTML challenge usually points to WAF or bot protection, and timeout means the URL is unreachable from the internet or responds too slowly.

Handler requirements

  • The URL must be reachable from the internet. Local addresses, private networks, and URLs with a username or password are not suitable.
  • HTTPS is recommended for production. HTTP is supported, but it provides weaker protection for data in transit.
  • The handler must accept the POST method and a JSON body without redirects.
  • Return 2xx only after your system has processed the event. 204 No Content is usually enough.
  • If the event cannot be processed safely, return an error response. 3xx, 4xx, 5xx, timeouts, and connection errors are treated as failed delivery.
  • If you use a firewall, bot protection, or allowlist, allow GAMEMONITORING IP addresses.
  • Do not return tokens, stack traces, SQL errors, or other internal details in the response body. The handler response is shown in the interface, so the error text must be safe and understandable.

Event data

Every Webhook arrives as a JSON body with core fields:

  • event_type — event to process.
  • event_id — unique event ID. Use it together with event_type for idempotency and duplicate-delivery protection.
  • is_test — marks a test delivery from the interface.
  • signature — signature of the event body.
Webhook event example
{
  "event_id": "9824cabb-2203-437e-9b6c-aba43dde3e4b",
  "event_type": "example.event",
  "is_test": false,
  "signature": "0ac4c97a5d934599dbd78985c4bcbb6926e77b4809d2be56333b1b25f638f064"
}

How to read this example: event_type shows which event must be processed; event_id must be stored before changing state; is_test: true means the handler should only verify delivery; signature is not business data and is used only to authenticate the request.

Event-specific logic depends on event_type. For server.vote, use the dedicated flow: Vote rewards.

If is_test is true, verify the signature and return 2xx, but do not change balances, issue items, or perform production side effects.

Handler response example

Choose one clear result for each incoming event:

  • 204 No Content — the signature is valid and the event has been processed. Return the same response for a test delivery and for a duplicate that was already processed.
  • 400 Bad Request — required fields are missing. This means a handler bug or an unexpected request body; do not run business logic.
  • 401 Unauthorized — the signature is invalid. Do not make API requests, do not change the database, and do not issue rewards.
  • 500 Internal Server Error — your database, queue, or internal service is temporarily unavailable. The delivery remains failed and can be retried after the cause is fixed.

For example, if the handler received the event, verified the signature, stored event_type + event_id, and processed the event, it can return 204 immediately. If the database is unavailable and the event cannot be stored, return 500 so delivery is not marked successful too early.

Signature verification

The signature is stored in the signature field. Verify it before any business logic, API request, or database change.

To verify it, take all event body fields except signature, sort keys alphabetically, and build a key=value string joined with &. Boolean values are written as true or false.

Signing string
event_id=9824cabb-2203-437e-9b6c-aba43dde3e4b&event_type=example.event&is_test=false

For the example above, the signing string is built only from event_id, event_type, and is_test. Then calculate HMAC-SHA256 with the signing token from Webhook settings and compare it with the request signature.

Precomputed signatures in the examples use the demo token paste-webhook-token-here. In your handler, use the token from Webhook settings.

In your handler:

  • build the signing string from sorted keys;
  • calculate HMAC-SHA256 with the signing token;
  • compare the result with signature using a constant-time helper: hash_equals in PHP, timingSafeEqual in Node.js, or compare_digest in Python;
  • return 401 when the signature is invalid.

Minimal handler

This example accepts any Webhook: it reads JSON, verifies signature, handles a test delivery, validates core fields, and returns 204. Add event-specific logic after signature verification.

php
<?php
$secret = 'paste-webhook-token-here';

$event = json_decode(file_get_contents('php://input'), true) ?: [];
$isTest = ($event['is_test'] ?? false) === true;
$signingData = array_replace($event, ['is_test' => $isTest ? 'true' : 'false']);

$fields = array_values(array_filter(array_keys($event), fn($field) => $field !== 'signature'));
sort($fields, SORT_STRING);

$signing = implode('&', array_map(fn($field) => $field . '=' . (string) ($signingData[$field] ?? ''), $fields));
$expected = hash_hmac('sha256', $signing, $secret);
$actual = (string) ($event['signature'] ?? '');

if (!hash_equals($expected, $actual)) {
    http_response_code(401);
    exit;
}

if ($isTest) {
    http_response_code(204);
    exit;
}

$eventType = (string) ($event['event_type'] ?? '');
$eventId = (string) ($event['event_id'] ?? '');

if ($eventType === '' || $eventId === '') {
    http_response_code(400);
    exit;
}

error_log('Accepted webhook event ' . $eventType . ' #' . $eventId);

http_response_code(204);

Duplicate delivery and deduplication

Webhook uses at-least-once delivery: the same event can arrive more than once. Any action that changes your system state must be idempotent for event_type + event_id.

Store the pair event_type and event_id in a table with a unique key. If the record already exists, the event has already been processed: return 204 and do not change state again.

Processed Webhook events table
CREATE TABLE gamemonitoring_webhooks (
  event_type varchar(64) NOT NULL,
  event_id varchar(100) NOT NULL,
  created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (event_type, event_id)
);

When a Webhook changes your database, store the event and perform the action in one transaction. If the handler issues a reward, inserting event_type + event_id and updating the reward must succeed together. If the insert does not create a new row, the event was already processed.

Do not use nickname, user ID, or server ID as the deduplication key: one user can trigger different events or repeat an allowed action later. The key must be event_type + event_id.

Example: the handler issued a reward, but the connection broke before GAMEMONITORING received 204. Later the delivery is retried, and the same event arrives again. Your handler must find the already stored event_type + event_id, avoid issuing the reward again, and return 204.

If the handler temporarily cannot process an event, return an error response. After the cause is fixed, delivery can be retried from the interface when retry is available for that event.

Testing and resend

A test delivery (is_test: true) checks the handler URL, signature, and HTTP response. The handler should follow the same receive path: read JSON, verify signature, recognize is_test, and return a successful 2xx response.

A test event must not change balance, inventory, roles, subscriptions, or other production data. A technical log and 204 response are enough for a test.

If delivery fails, the interface shows the status, HTTP status code, and handler response. After fixing the cause, a failed delivery can be resent when retry is available for that event.