Webhook

Webhook प्लेटफ़ॉर्म पर action होते ही GAMEMONITORING event को आपके system तक भेजता है। यह JSON body वाला सामान्य POST request है, जिससे आपकी website, panel या game service अपने-आप प्रतिक्रिया दे सकती है।

Vote rewards के लिए पहले Webhook setup करें, फिर यह अलग flow use करें: वोट पुरस्कार।

सेटअप

यह setup GAMEMONITORING project को आपके handler से जोड़ता है और incoming requests verify करने के लिए signing token देता है।

  1. My projects खोलें, project create करें या existing project चुनें, फिर Webhook settings में जाएं।
  2. Public HTTPS endpoint बनाएं जो Content-Type: application/json के साथ POST accept करे और redirect न करे।
  3. Webhook settings में पूरा handler URL डालें, जैसे https://panel.example.com/gamemonitoring-webhook, और उसे save करें।
  4. उसी block से signing token copy करें और उसे handler script में डालें।
  5. Handler में signature verify करें, required event_type process करें और event process होने के बाद ही successful 2xx response लौटाएं।

Setup के बाद interface से test Webhook भेजें और delivery status check करें। Example URL के लिए server को /gamemonitoring-webhook path पर POST accept करना चाहिए।

अगर test fail हो, तो handler response देखें: 401 signature problem है, 403 या HTML challenge आम तौर पर WAF/bot protection है, timeout का मतलब URL internet से reachable नहीं है या बहुत slow है।

Handler की आवश्यकताएं

  • URL internet से reachable होना चाहिए। Local addresses, private networks और login/password वाले URL suitable नहीं हैं।
  • Production के लिए HTTPS recommended है। HTTP supported है, लेकिन transit में data को कम सुरक्षा देता है।
  • Handler को redirect के बिना POST और JSON body accept करनी चाहिए।
  • 2xx तभी लौटाएं जब आपका system event process कर चुका हो। आम तौर पर 204 काफी है।
  • अगर event safely process नहीं हो सकता, error status लौटाएं। 3xx, 4xx, 5xx, timeout या connection error failed delivery मानी जाती है।
  • अगर firewall, bot protection या allowlist है, तो GAMEMONITORING IP addresses को exceptions में जोड़ें।
  • Response body में tokens, stack trace, SQL errors या internal details न लौटाएं। Handler response interface में दिखता है, इसलिए error text safe और clear होना चाहिए।

Event data

हर Webhook मुख्य fields वाली JSON body के रूप में आता है:

  • event_type — कौन सा event process करना है।
  • event_id — unique event ID। Idempotency और repeated delivery protection के लिए इसे event_type के साथ use करें।
  • is_test — interface से test delivery को mark करता है।
  • signature — event body की signature।
Webhook event example
{
  "event_id": "9824cabb-2203-437e-9b6c-aba43dde3e4b",
  "event_type": "example.event",
  "is_test": false,
  "signature": "0ac4c97a5d934599dbd78985c4bcbb6926e77b4809d2be56333b1b25f638f064"
}

Example पढ़ना: event_type बताता है कि कौन सा event process करना है, event_id state बदलने से पहले save करें, is_test: true सिर्फ delivery check है, और signature केवल request authentication के लिए है।

Event-specific logic event_type पर depend करती है। server.vote के लिए अलग flow use करें: वोट पुरस्कार।

अगर is_test true है, signature verify करें और 2xx लौटाएं, लेकिन balance या inventory न बदलें।

Handler response example

हर incoming event के लिए साफ result चुनें:

  • 204 No Content — signature valid है और event processed है। Test delivery और already processed duplicate event के लिए भी यही लौटाएं।
  • 400 Bad Request — required fields missing हैं। Business logic run न करें।
  • 401 Unauthorized — signature invalid है। API request न करें, database न बदलें और reward न दें।
  • 500 Internal Server Error — database, queue या internal service temporary unavailable है। Delivery failed रहेगी और fix के बाद retry हो सकती है।

Example: handler ने signature verify किया, event_type + event_id save किया और event process किया, तो वह 204 लौटा सकता है। Database unavailable हो तो 500 लौटाएं ताकि delivery जल्दी successful न मानी जाए।

Signature verification

signature field में signature होती है। किसी भी business logic, API request या database change से पहले इसे verify करें।

Verify करने के लिए signature छोड़कर body के सभी fields लें, keys alphabetically sort करें और & से जुड़ी key=value string बनाएं। Boolean values true या false लिखी जाती हैं।

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

ऊपर वाले example में signing string केवल event_id, event_type और is_test से बनती है। फिर Webhook settings के token से HMAC-SHA256 calculate करें और request की signature से compare करें।

Examples में precomputed signatures demo token paste-webhook-token-here से calculate की गई हैं। अपने handler में Webhook settings वाला token use करें।

अपने handler में:

  • sorted keys से signing string बनाएं;
  • signing token के साथ HMAC-SHA256 calculate करें;
  • result को signature से constant-time comparison helper से compare करें: PHP में hash_equals, Node.js में timingSafeEqual, या Python में compare_digest;
  • signature invalid हो तो 401 लौटाएं।

Minimal handler

यह example कोई भी Webhook accept करता है: JSON पढ़ता है, signature verify करता है, test delivery handle करता है, मुख्य fields validate करता है और 204 लौटाता है। Event-specific logic 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 और deduplication

Webhook delivery at-least-once model पर चलती है: वही event एक से अधिक बार आ सकता है। System state बदलने वाला हर action event_type + event_id के आधार पर idempotent होना चाहिए।

event_type और event_id pair को unique key वाली table में store करें। अगर record पहले से मौजूद है, event already processed है: 204 लौटाएं और state दोबारा न बदलें।

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)
);

जब Webhook आपकी database बदलता है, event store करना और action चलाना एक ही transaction में करें। अगर handler reward देता है, तो event_type + event_id insert और reward update साथ में successful होने चाहिए। अगर insert नई row नहीं बनाता, event already processed है।

Nickname, user ID या server ID को deduplication key की तरह use न करें: वही user अलग events trigger कर सकता है या allowed action बाद में दोहरा सकता है। Key event_type + event_id होनी चाहिए।

Example: handler ने reward दे दिया, लेकिन GAMEMONITORING को 204 मिलने से पहले connection टूट गया। Retry पर वही event फिर आएगा। Handler को saved event_type + event_id मिलना चाहिए, reward दोबारा नहीं देना चाहिए और 204 लौटाना चाहिए।

अगर handler temporary रूप से event process नहीं कर सकता, error response लौटाएं। Cause fix होने के बाद interface से delivery दोबारा भेजी जा सकती है, अगर उस event के लिए resend available है।

Test और दोबारा भेजना

Test delivery (is_test: true) handler URL, signature और HTTP response check करती है। Handler को वही processing path चलाना चाहिए: JSON पढ़ें, signature verify करें, is_test पहचानें और successful 2xx response लौटाएं।

Test event balance, inventory, roles, subscriptions या production data नहीं बदलना चाहिए। Test के लिए technical log और 204 response काफी हैं।

अगर delivery fail होती है, interface में status, HTTP status code और handler response दिखते हैं। Cause fix होने के बाद failed delivery दोबारा भेजी जा सकती है, अगर उस event के लिए resend available है।