POST /apiv2/reports/webhooks

Bir URL kaydedin; durumu sürekli sorgulamak yerine bir rapor hazır olduğunda NETTS onu çağıracaktır.

Bu uç noktalar sipariş webhook'larından ayrıdır. Oraya kaydolmak sizi rapor bildirimlerine abone yapmaz ve bunun tersi de geçerlidir. İletim formatı — imza, başlıklar, yeniden deneme davranışı — tamamen aynıdır, bu nedenle biri için yazılmış bir işleyici diğeri için de çalışır.

Uç nokta temel URL'si

https://netts.io/apiv2/reports/webhooks

İstek Başlıkları

Başlık	Gerekli	Açıklama
X-API-KEY	evet	Kontrol panelinden alınan API anahtarı
X-Real-IP	evet	Anahtar beyaz listesinde yer alan bir adres

Birincil ve yedek

Hesap başına en fazla iki uç nokta. primary her şeyi alır. backup yalnızca birincil uç noktaya teslimatta deneme hakları tükendikten sonra kullanılır — ve birincilin değil, kendi gizli anahtarıyla imzalanır.

Kayıt

curl -s -X POST 'https://netts.io/apiv2/reports/webhooks' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-Real-IP: 203.0.113.10' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com/netts/reports", "role": "primary"}'

{
  "status": "success",
  "code": 10000,
  "data": {
    "id": 1,
    "url": "https://example.com/netts/reports",
    "role": "primary",
    "is_active": true,
    "created_at": "2026-09-06 17:05:12+00:00",
    "updated_at": "2026-09-06 17:05:12+00:00",
    "secret": "whsec_<64 hex characters>"
  }
}

Gizli anahtar yalnızca bir kez, burada gösterilir. Bir daha asla döndürülmez — ne liste uç noktası ne de okuma uç noktası tarafından. Aldığınızda kaydedin. Kaybolursa yenisini oluşturun:

curl -s -X POST 'https://netts.io/apiv2/reports/webhooks/1/rotate-secret' \
  -H 'X-API-KEY: your-api-key' -H 'X-Real-IP: 203.0.113.10'

Yenileme işlemi anında yürürlüğe girer ve eski gizli anahtar doğrulamayı durdurur; bu nedenle kesintiye tahammülünüz yoksa önce yeni değeri dağıtın.

Yönetim

Yöntem	Yol	Eylem
GET	/apiv2/reports/webhooks	gizli anahtarlar olmadan sizinkileri listeler
GET	/apiv2/reports/webhooks/{id}	bir tanesini okur
PATCH	/apiv2/reports/webhooks/{id}	url değiştirir veya is_active: false ile duraklatır
DELETE	/apiv2/reports/webhooks/{id}	kaldırır

URL genel HTTPS olmalıdır. Geri döngü (loopback), özel ve yerel bağlantı (link-local) adresleri ile URL içindeki kimlik bilgileri reddedilir. Reddedilen her şey gerekçesiyle birlikte 422 olarak döner. Kontrol, her teslimattan hemen önce tekrar çalıştırılır, bu nedenle daha sonra özel bir adrese çözümlenen bir uç nokta bildirim almayı durdurur.

Ne gönderiyoruz

{
  "event": "report.ready",
  "delivery_id": 4,
  "order_id": "REPxxxxxxxxxxxx",
  "order_type": "statement",
  "client_request_id": "stmt-2026-09-usdt",
  "status": "done",
  "format": "csv",
  "download_url": "/apiv2/reports/REPxxxxxxxxxxxx/download",
  "expires_at": "2026-10-06 15:48:04+00:00",
  "artifact": { "sha256": "…", "size_bytes": 696 },
  "confirmed_at": "2026-09-06T15:48:04Z"
}

Alan	Açıklama
event	report.ready — işleyiciniz için yönlendirme anahtarı
delivery_id	Tekilleştirme anahtarı. Ayrıca X-Netts-Delivery başlığı olarak da gönderilir
order_id	Raporu sıraya aldığınızda size verilen sipariş numarası
order_type	statement veya balance_at_date
download_url	Dosyayı almak için https://netts.io adresine göreli yol
artifact.sha256	İndirdiğiniz dosyayı doğrulayabilmeniz için sağlama toplamı
confirmed_at	UTC

Tüm zaman damgaları UTC formatındadır.

İmzayı doğrulama

X-Netts-Signature: sha256=<hex>
X-Netts-Timestamp: <unix seconds>
X-Netts-Delivery:  <delivery_id>

İmza, isteği alan uç noktanın gizli anahtarı ile hesaplanan "<timestamp>." + ham gövde üzerinde HMAC-SHA256'dır. Sabit zamanda karşılaştırın ve zaman damgası ±5 dakikalık aralığın dışına düşen her şeyi reddedin.

import hmac, hashlib, time

def verify(raw_body: bytes, sig_header: str, ts_header: str, secret: str) -> bool:
    if abs(time.time() - int(ts_header)) > 300:      # anti-replay
        return False
    signed = f"{ts_header}.".encode() + raw_body
    expected = "sha256=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig_header)

İsteğin ulaştığı URL'nin gizli anahtarıyla imzalayın: birincil ve yedek farklı gizli anahtarlara sahiptir.

Teslimat en az bir kez yapılır

Düşen bir yanıt yeniden denemeye neden olur, bu nedenle aynı olay iki kez gelebilir.

1. delivery_id ile tekilleştirin. Yinelenen istek sizin tarafınızda hiçbir işlem yapmamalıdır (no-op).
2. Harekete geçmeden önce imzayı doğrulayın, sonrasında değil.
3. Yalnızca olayı depoladıktan sonra 2xx yanıtı verin. Bunun dışındaki her şey veya zaman aşımı bir başarısızlık olarak kabul edilir ve yeniden denenir.

Tek bir uç noktaya yapılan yeniden denemeler 1 dakika, 5 dakika, 15 dakika, 1 saat, 6 saat ve 24 saat aralıklarla gerçekleşir — toplamda altı deneme, 31 saatin biraz üzerinde bir süreye yayılır. Bunlar tükendiğinde ve bir backup kaydettiyseniz, teslimat oraya geçer ve zamanlama yedeğin kendi gizli anahtarıyla baştan başlar. delivery_id süreç boyunca aynı kalır, bu nedenle birincilde başarısız olup yedekte başarılı olan bir olay yine de tek bir olaydır.

Yönlendirmeler takip edilmez.

İstek Limitleri

Tüm istemciler arasında paylaşılan, uç nokta başına saniyede 10 istek.

Hatalar

Kayıt işlemi 201, silme işlemi gövdesiz 204, diğer her şey 200 yanıtı verir.

HTTP	Anlamı
401	anahtar eksik veya geçersiz ya da kaynak IP beyaz listede değil
404	hesabınızda böyle bir uç nokta yok
409	istenen rol zaten alınmış — role primary is already taken
422	URL reddedildi veya PATCH gövdesi değiştirilecek bir şey içermiyordu
429	istek limiti aşıldı

Reddedilen bir URL, gerekçesi açıkça belirtilerek 422 olarak döner; böylece bunu adresi yazan kişiye gösterebilirsiniz:

{"status": "error", "code": -4, "msg": "url: Value error, invalid webhook_url: resolved address 127.0.0.1 is not public"}

İfadeler only https:// URLs are allowed, credentials in URL are not allowed ve resolved address <ip> is not public şeklindedir. Sonuncusu kayıt sırasında ve her teslimattan hemen önce tekrar çözümlenir; bu nedenle daha sonra özel bir adrese işaret eden bir alan adı bildirim almayı durdurur.

İlgili

• Hesap özeti dosyaları — bu bildirimi tetikleyen raporun sipariş edilmesi
• Sipariş webhook'ları — enerji, bant genişliği ve etkinleştirme olayları için ayrı kayıt alanı