Webhook'lara genel bakış

Webhook’lar

Hesabınızın tek bir webhook URL’si vardır ve tüm olaylar oraya gider. Dashboard → API sayfasından veya Webhook yapılandırma ile ayarlayın.

Olaylar

Bugün altı olay mevcut.

Olay	Ne zaman gönderilir
`order.updated`	Bir enerji veya bandwidth siparişi durum değiştirdiğinde — yalnızca API üzerinden oluşturulan siparişler için
`subscription.transfer`	Smart Mode, izlenen bir adresten yapılan transferin bedelini ödediğinde
`package.transfer`	Bir Transfer Package, kendi adresinden yapılan bir transferin bedelini ödediğinde
`package.completed`	Bir Transfer Package transferleri karşılamayı bıraktığında
`package.activated`	Bir Transfer Package etkinleştiğinde
`package.expired`	Ödenmemiş bir Transfer Package faturasının süresi dolduğunda

order.updated yalnızca bir API anahtarıyla oluşturulan siparişler için gönderilir. Web sitesinden veya Telegram botundan yapılan alımlar webhook üretmez — aynı hesap Smart Mode olaylarını normal biçimde almaya devam etse bile.

Zarf

Her teslimatta aynı üç üst düzey anahtar bulunur. timestamp, olayı oluşturduğumuz andır; ISO-8601, UTC.

Response

{
  "event": "order.updated",
  "data": { },
  "timestamp": "2026-09-14T14:51:16.986341+00:00"
}

Başlıklar:

Başlık	Değer
`Content-Type`	`application/json`
`X-Webhook-Signature`	`sha256=<hex>` — aşağıdaki «İmzanın doğrulanması» bölümüne bakın
`Host`	URL’nizin host’u

`order.updated`

number

Sipariş kimliği.

string

energy veya bandwidth.

string

processing, filled, partial, failed, reclaimed veya reclaim_failed. Doğrunun kaynağı bu alandır — aşağıdaki uyarıya bakın.

string

Kaynağın devredildiği adres.

number

Sipariş edilen miktar — enerji birimi ya da bandwidth puanı.

number

volume ile aynı. Hangi alanın ne anlama geldiğini araştırmadan beklenen ile teslim edileni karşılaştırabilmek için bulunur.

number

Şu ana kadar gerçekte ne kadarının devredildiği. Sipariş filled olduğunda volume ile eşittir; processing ve partial durumunda şimdiye kadar teslim edilen parçaların toplamı, başarısızlıkta 0.

string

Siparişin TRX cinsinden fiyatı, ondalık metin olarak.

string | null

Kaynağı devreden işlem.

string | null

Kiralama bitince kaynağı geri alan işlem.

string | null

Kaynağın geri alınmasının planlandığı an, ISO-8601; zamanlayıcıyla geri alınmayan siparişlerde null.

Response

{
  "event": "order.updated",
  "data": {
    "id": 247033,
    "type": "energy",
    "status": "filled",
    "target_address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "volume": 65000,
    "expected_volume": 65000,
    "delivered_volume": 65000,
    "price_trx": "2.75",
    "delegate_txid": "a1b2c3d4e5f6...",
    "undelegate_txid": null,
    "reclaim_at": "2026-09-15T07:44:56+00:00"
  },
  "timestamp": "2026-09-14T14:51:16.986341+00:00"
}

Sonucu status alanına göre değerlendirin, delegate_txid var diye değil. Başarısız bir sipariş de işlem kimliği taşıyabilir — arızanın incelenebilmesi için bunu bilerek saklıyoruz. Kaynağı alıp almadığınızı yalnızca status söyler.

Büyük siparişleri içeride parçalara böleriz, ama bu bizim işimiz: siz sipariş başına tek bir webhook alırsınız, parça başına değil.

`subscription.transfer`

number

Transferin ait olduğu Smart Mode aboneliği.

string

Transferin çıktığı izlenen adres.

string | null

Aboneliğe verdiğiniz etiket.

string

Zincir üzerindeki transfer işlemi.

number

Bu devrin kaç transferi kapsadığı.

number

Onlar için devredilen enerji.

string

Enerji için tahsil edilen tutar, TRX cinsinden.

string | null

Ek olarak tahsil edilen bandwidth; tahsil edilmediyse null.

string

Tahsilat sonrası hesap bakiyeniz.

string

Transferin işlendiği an. Dikkat: bu alan data içindedir ve zarfın kendi timestamp alanından farklıdır.

Response

{
  "event": "subscription.transfer",
  "data": {
    "subscription_id": 412,
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "label": "payouts",
    "tx_hash": "9f8e7d6c5b4a...",
    "transfer_count": 1,
    "energy_delegated": 65000,
    "fee_trx": "2.75",
    "bw_fee_trx": null,
    "balance_after_trx": "376.63",
    "timestamp": "2026-09-14T14:51:16.512033+00:00"
  },
  "timestamp": "2026-09-14T14:51:16.986341+00:00"
}

Transfer Package olayları

Dört package.* olayı paketin sahibi olan hesaba gönderilir. Oturum açmadan veya API anahtarı olmadan faturayla satın alınan bir paketin sahibi yoktur ve olay üretmez. İptal edilen faturalar, reddedilen satın almalar ve manuel incelemedeki satın almalar da olay üretmez; incelemedeki bir paket etkinleştirildiğinde package.activated gönderir. Her package.* olayı data içinde şu alanları taşır:

number

Paket kimliği — Paketleri Listele yanıtındaki id.

string

Paketin hizmet verdiği adres.

string

Olaydan sonraki paket durumu: package.transfer için active veya completed, package.completed için completed, package.activated için active, package.expired için expired.

number

Paketin satın alındığı transfer sayısı.

number

Olayın bildirdiği değişiklikten sonra bu pakette kalan transfer sayısı — fark değil, mutlak bir sayı.

Olaylar sırasız gelebilir. Her biri ayrı ayrı, yaklaşık 35 saniyeye kadar yeniden denemelerle teslim edilir; bu yüzden bir transferin yol açtığı package.completed, o transferin package.transfer olayından önce, bir package.transfer da package.activated olayından önce gelebilir. Her package_id için gördüğünüz en düşük remaining değerini saklayın: bu değer hiç artmaz. completed ve expired kesindir.

remaining olay olmadan da azalabilir. Çok transferli bir paket, günlük abonelik olarak günde bir transfer düşer — ilki etkinleştirmede, bu yüzden 500 transferlik bir paket remaining: 499 ile başlar — ve bu kesinti bildirilmez. Aynı adresten aynı blokta yapılan iki transfer aynı remaining değerini bildirebilir. remaining değerini bir ipucu, Paketleri Listele yanıtını ise doğruluk kaynağı olarak kabul edin.

Bir yeniden denemeyi tanımak için package.transfer olayında (package_id, tx_hash), diğerlerinde (event, package_id) kullanın: yeniden deneme aynı gövdeyi, aynı timestamp değerini ve aynı imzayı taşır.

`package.transfer`

Adresten yapılan bir transferin bedeli bir paketten ödendi. Transferin düşüldüğü her paket için bir kez gönderilir — neredeyse her zaman transfer başına bir olay; bir paketin son transferini alıp sonrakinde devam eden bir transfer, her biri için bir olay üretir.

string

Zincirdeki transfer işlemi.

number

Bu işlem için bu paketten düşülen transfer sayısı. USDT bulunmayan bir adrese yapılan transfer iki kat enerji gerektirir ve 2 sayılır; bu iki birim iki pakete bölünebilir.

Burada bu transfer paketi tükettiyse status değeri completed olur.

Response

{
  "event": "package.transfer",
  "data": {
    "package_id": 318,
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "status": "active",
    "quota_total": 500,
    "remaining": 312,
    "tx_hash": "9f8e7d6c5b4a...",
    "units": 1
  },
  "timestamp": "2026-10-15T14:51:16.986341+00:00"
}

`package.completed`

Paket transferleri karşılamayı bıraktı.

string

transfer — paketi bir transfer tüketti; subscription — paketi günlük kesinti tüketti; manual — paketi destek ekibi kapattı. manual sonrasında remaining sıfırdan büyük olabilir, ancak bu transferler artık kullanılamaz.

string | null

reason: "transfer" olduğunda paketi kapatan transfer; aksi halde null.

Kalanı olmayan bir paket — örneğin ilk günlük kesintisi tek transferini almış, tek transferlik normal bir paket — sonraki transferle kendine ait bir package.transfer olmadan kapanır: yalnızca o transferin tx_hash değeriyle package.completed alırsınız.

Response

{
  "event": "package.completed",
  "data": {
    "package_id": 318,
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "status": "completed",
    "quota_total": 500,
    "remaining": 0,
    "reason": "transfer",
    "tx_hash": "9f8e7d6c5b4a..."
  },
  "timestamp": "2026-10-15T14:51:16.986341+00:00"
}

`package.activated`

Paket etkinleşti ve bundan sonra transferleri enerji alır. Her etkinleştirmede gönderilir — yanıtı zaten active diyen bakiyeyle satın alma ve ödemesi zincirde görüldükten kısa süre sonra paketi etkinleştiren fatura ödemesi dahil.

string

Paketin nasıl ödendiği: tam olarak balance, TRX veya USDT.

Response

{
  "event": "package.activated",
  "data": {
    "package_id": 318,
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "status": "active",
    "quota_total": 500,
    "remaining": 499,
    "payment_method": "USDT"
  },
  "timestamp": "2026-10-15T14:51:16.986341+00:00"
}

`package.expired`

Bir paketin faturası 30 dakikalık süresi içinde ödenmedi. Hiçbir ücret alınmadı; yeni bir fatura için yeniden satın alın. Ek alan yoktur; remaining, quota_total değerine eşittir ve kullanılamaz.

Response

{
  "event": "package.expired",
  "data": {
    "package_id": 319,
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "status": "expired",
    "quota_total": 500,
    "remaining": 500
  },
  "timestamp": "2026-10-15T15:21:16.986341+00:00"
}

Teslimat

En çok 3 deneme, aralarında 1 saniye ve ardından 4 saniye bekleme ile. Başarıdan sonra ve son denemeden sonra bekleme yoktur.
Deneme başına 10 saniye zaman aşımı.
Herhangi bir 2xx bekleriz. Bunun dışındaki her şey başarısız deneme sayılır.
Yönlendirmeler izlenmez. 301/302 bir sıçrama değil, başarısız bir denemedir.
Kaçan olaylar sonradan yeniden gönderilmez. Üç deneme de başarısız olursa o olay kaybolur; tekrar beklemek yerine Sipariş sorgulama veya Paketleri Listele ile mutabakat yapın.

URL’niz genel bir adrese çözümlenmelidir. Loopback, özel ve link-local aralıklar reddedilir; hiç çözümlenmeyen bir host da öyle — her iki durumda da hiçbir şey gönderilmez ve günlüğe satır yazılmaz.

İmzanın doğrulanması

Her istek X-Webhook-Signature: sha256=<hex> taşır: webhook gizli anahtarınızla, ham istek gövdesi üzerinden hesaplanmış bir HMAC-SHA256. Kontrolünüzün çalışıp çalışmayacağını iki ayrıntı belirler:

Karşılaştırmadan önce sha256= önekini ayırın. Başlık düz bir onaltılık özet değildir.
Aldığınız baytların özetini alın, yeniden serileştirilmiş bir nesnenin değil. JSON’u ayrıştırıp yeniden yazmak anahtar sırasını ve boşlukları değiştirir; imza hiçbir zaman tutmaz.

İmzalama anahtarınız Dashboard → API sayfasında, webhook URL’sinin yanında görünür. API anahtarlı isteklere döndürülmez — okumak için web sitesinde oturum açmanız gerekir.

import hashlib
import hmac

def verify_webhook(raw_body: bytes, signature_header: str, secret: str) -> bool:
    prefix, _, received = signature_header.partition("=")
    if prefix != "sha256" or not received:
        return False
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received)

const crypto = require("crypto");

function verifyWebhook(rawBody, signatureHeader, secret) {
  const [prefix, received] = String(signatureHeader).split("=");
  if (prefix !== "sha256" || !received) return false;
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(received);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

İçeriğe göre işlem yapmadan önce imzayı doğrulayın ve sabit zamanda karşılaştırın (hmac.compare_digest / crypto.timingSafeEqual). == ile karşılaştırmak zamanlama üzerinden bilgi sızdırır.

Temel API

Bant Genişliği Kiralamaları

Otomatik Dolum

Siparişler

Faturalar

Smart Mode

Transfer Paketleri

Hesap

Webhooks

Webhook'lara genel bakış

Webhook’lar

Olaylar

Zarf

`order.updated`

`subscription.transfer`

Transfer Package olayları

`package.transfer`

`package.completed`

`package.activated`

`package.expired`

Teslimat

İmzanın doğrulanması

​Webhook’lar

​Olaylar

​Zarf

​order.updated

​subscription.transfer

​Transfer Package olayları

​package.transfer

​package.completed

​package.activated

​package.expired

​Teslimat

​İmzanın doğrulanması

Webhook’lar

Olaylar

Zarf

`order.updated`

`subscription.transfer`

Transfer Package olayları

`package.transfer`

`package.completed`

`package.activated`

`package.expired`

Teslimat

İmzanın doğrulanması