Webhook

Webhook, platformda bir işlem gerçekleştiğinde GAMEMONITORING olayını sisteminize hemen iletir. JSON gövdeli sıradan bir POST isteğidir; web siteniz, paneliniz veya oyun servisiniz otomatik tepki verebilir.

Oy ödülleri için önce Webhook’u ayarlayın, ardından ayrı akışı kullanın: Oy ödülleri.

Bağlantı

Bu ayar bir GAMEMONITORING projesini handler’ınıza bağlar ve gelen istekleri doğrulamak için imzalama tokenı sağlar.

Projelerim sayfasını açın, proje oluşturun veya mevcut bir projeyi seçin, ardından Webhook ayarlarına gidin.
Content-Type: application/json ile POST kabul eden ve yönlendirme yapmayan herkese açık bir HTTPS endpoint oluşturun.
Webhook ayarlarında tam handler URL’sini girin, örneğin https://panel.example.com/gamemonitoring-webhook, ve kaydedin.
İmzalama tokenını aynı bloktan kopyalayın ve handler scriptinize ekleyin.
Handler’da signature doğrulayın, gerekli event_type değerini işleyin ve başarılı 2xx yanıtını yalnızca olay işlendikten sonra dönün.

Kurulumdan sonra arayüzden test Webhook gönderin ve teslimat durumunu kontrol edin. Örnek URL için sunucu /gamemonitoring-webhook path’inde POST kabul etmelidir.

Test başarısızsa önce handler yanıtına bakın: 401 imza sorununu, 403 veya HTML challenge genellikle WAF ya da bot protection sorununu, timeout ise URL’nin internetten erişilemediğini veya çok yavaş yanıt verdiğini gösterir.

Handler gereksinimleri

URL internetten erişilebilir olmalıdır. Lokal adresler, özel ağlar ve kullanıcı adı veya parola içeren URL’ler uygun değildir.
Canlı ortam için HTTPS önerilir. HTTP desteklenir ancak aktarım sırasında veriyi daha zayıf korur.
Handler yönlendirme yapmadan POST ve JSON gövde kabul etmelidir.
2xx yanıtını yalnızca sisteminiz olayı işledikten sonra dönün. Genellikle 204 yeterlidir.
Olay güvenli şekilde işlenemiyorsa hata durumu dönün. 3xx, 4xx, 5xx, timeout veya bağlantı hatası başarısız teslimat sayılır.
Firewall, bot protection veya allowlist kullanıyorsanız GAMEMONITORING IP adreslerini istisnalara ekleyin.
Yanıt gövdesinde token, stack trace, SQL hatası veya başka iç detaylar döndürmeyin. Handler yanıtı arayüzde gösterilir; hata metni güvenli ve anlaşılır olmalıdır.

Olay verisi

Her Webhook temel alanlara sahip JSON gövdesiyle gelir:

event_type — hangi olayın işlenmesi gerektiği.
event_id — benzersiz olay ID’si. Idempotency ve tekrarlı teslimat koruması için event_type ile birlikte kullanın.
is_test — arayüzden gelen test teslimatını belirtir.
signature — olay gövdesinin imzası.

Webhook olayı örneği

{
  "event_id": "9824cabb-2203-437e-9b6c-aba43dde3e4b",
  "event_type": "example.event",
  "is_test": false,
  "signature": "0ac4c97a5d934599dbd78985c4bcbb6926e77b4809d2be56333b1b25f638f064"
}

Örneği okuma şekli: event_type hangi olayın işlenmesi gerektiğini gösterir, event_id durum değişmeden önce kaydedilir, is_test: true sadece teslimat kontrolü demektir, signature ise yalnızca istek doğrulaması içindir.

Olay mantığı event_type değerine bağlıdır. server.vote için ayrı akışı kullanın: Oy ödülleri.

is_test true ise imzayı doğrulayın ve 2xx dönün; bakiye, envanter veya canlı ortam verilerini değiştirmeyin.

Handler yanıtı örneği

Her gelen olay için net bir sonuç seçin:

204 No Content — imza geçerli ve olay işlendi. Test teslimatı ve daha önce işlenmiş tekrar için de bunu dönün.
400 Bad Request — zorunlu alanlar eksik. İş mantığını çalıştırmayın.
401 Unauthorized — imza geçersiz. API isteği yapmayın, veritabanını değiştirmeyin, ödül vermeyin.
500 Internal Server Error — veritabanı, kuyruk veya iç servis geçici olarak kullanılamıyor. Teslimat başarısız kalır ve düzeltmeden sonra tekrar gönderilebilir.

Örnek: handler imzayı doğruladı, event_type + event_id kaydetti ve olayı işlediyse hemen 204 dönebilir. Veritabanı kullanılamıyorsa 500 dönün ki teslimat erken başarılı sayılmasın.

İmza doğrulama

İmza signature alanındadır. Herhangi bir iş mantığından, API isteğinden ve veritabanı değişikliğinden önce doğrulayın.

Doğrulama için signature hariç tüm gövde alanlarını alın, anahtarları alfabetik sıralayın ve & ile birleştirilmiş key=value imza dizesi oluşturun. Boolean değerler true veya false yazılır.

İmzalanacak string

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

Yukarıdaki örnekte imza dizesi yalnızca event_id, event_type ve is_test ile oluşturulur. Sonra Webhook ayarlarındaki token ile HMAC-SHA256 hesaplayıp istek içindeki signature ile karşılaştırın.

Örneklerdeki hazır imzalar demo tokenı paste-webhook-token-here ile hesaplanmıştır. Kendi handler’ınızda Webhook ayarlarındaki tokenı kullanın.

Kendi tarafınızda:

sıralı anahtarlardan imza dizesini oluşturun;
imzalama tokenı ile HMAC-SHA256 hesaplayın;
sonucu signature ile sabit süreli karşılaştırma yapan bir fonksiyonla kontrol edin: PHP’de hash_equals, Node.js’te timingSafeEqual veya Python’da compare_digest;
imza geçersizse 401 dönün.

Minimal handler

Bu örnek herhangi bir Webhook kabul eder: JSON okur, signature doğrular, test teslimatını işler, temel alanları doğrular ve 204 döner. Olay bazlı mantığı imza doğrulamasından sonra ekleyin.

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

Tekrarlı teslimat ve tekilleştirme

Webhook teslimatı at-least-once modelindedir: aynı olay birden fazla kez gelebilir. Sistem durumunu değiştiren her işlem event_type + event_id ile idempotent olmalıdır.

event_type ve event_id çiftini benzersiz anahtarlı bir tabloda saklayın. Kayıt zaten varsa olay daha önce işlenmiştir: 204 dönün ve durumu tekrar değiştirmeyin.

İşlenmiş Webhook olayları tablosu

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 veritabanınızı değiştiriyorsa olayı kaydetmeyi ve aksiyonu aynı transaction içinde yapın. Handler ödül veriyorsa, event_type + event_id eklemesi ve ödül güncellemesi birlikte başarılı olmalıdır. Ekleme yeni satır oluşturmadıysa olay zaten işlenmiştir.

Nickname, kullanıcı ID’si veya server ID’sini tekilleştirme anahtarı olarak kullanmayın: aynı kullanıcı farklı olaylar oluşturabilir veya izin verilen bir aksiyonu daha sonra tekrar yapabilir. Anahtar event_type + event_id olmalıdır.

Örnek: handler ödülü verdi ama GAMEMONITORING 204 almadan bağlantı koptu. Teslimat tekrarlandığında aynı event yeniden gelir. Handler kayıtlı event_type + event_id bulmalı, ödülü ikinci kez vermemeli ve 204 dönmelidir.

Handler olayı geçici olarak işleyemiyorsa başarısız yanıt dönün. Sebep düzeltildikten sonra, bu olay için tekrar gönderme varsa teslimat arayüzden tekrar gönderilebilir.

Testler ve tekrar gönderme

Test teslimatı (is_test: true) handler URL’sini, imzayı ve HTTP yanıtını kontrol eder. Handler aynı işleme yolunu izlemelidir: JSON okur, signature doğrular, is_test değerini tanır ve başarılı 2xx yanıtı döner.

Test olayı bakiye, envanter, roller, abonelikler veya diğer canlı verileri değiştirmemelidir. Test için teknik log ve 204 yanıtı yeterlidir.

Teslimat hata ile biterse arayüzde durum, HTTP kodu ve handler yanıtı gösterilir. Sebep düzeltildikten sonra, bu olay için tekrar gönderme varsa başarısız teslimat yeniden gönderilebilir.