TicketWave etkinliklerini imzalı HTTP istekleri olarak kendi uygulamanızda alın.

Webhook'lar

Bir webhook, TicketWave'in size gönderdiği bir HTTP isteğidir. Sunucunuzda bir şey olduğunda — bir bilet açıldığında, bir üye kara listeye alındığında — TicketWave, sahip olduğunuz bir URL'ye JSON gövdeli bir POST gönderir.

Bu, Log Channels ile arasındaki farktır: log kanalları, insanların okuyabilmesi için Discord'a bir embed yazar; webhook'lar ise ham etkinliği kodunuza teslim eder.

Webhook'lar bir premium özelliktir. Premium olmadan endpoint oluşturulamaz ve hiçbir etkinlik teslim edilmez.

Bir Endpoint Oluşturun

Endpointler sayfasını açın

Sunucu paneli → Webhooks → Endpoints.

Bir endpoint ekleyin

Add Endpoint düğmesine tıklayın ve iki alanı doldurun:

Field	Description
Endpoint URL	İstekleri alan `https://` URL'si
Event Types	Bu endpoint'in alması gereken etkinlikler

Bir endpoint yalnızca işaretlediğiniz türleri alır. Hiçbirini seçmek mümkün değildir — en az bir tane seçin.

İmzalama gizli anahtarını kopyalayın

TicketWave, endpoint oluşturulduğu anda bir imzalama gizli anahtarı (whsec_…) üretir. Endpointler listesini açın, göz simgesiyle görünür hale getirin ve uygulamanızın yapılandırmasına kopyalayın.

Gizli anahtarı bir parola gibi düşünün. Ona sahip olan herkes, imza kontrolünüzü geçen sahte istekler oluşturabilir. Onu bir ortam değişkeninde tutun, asla depoda saklamayın.

Bir test etkinliği gönderin

Endpoint satırındaki Send test event düğmesini (kâğıt uçak) kullanın. Bu, yük içinde "test": true bulunan gerçek ve tamamen imzalı bir istek gönderir; böylece gerçek bir bilet buna bağlı hale gelmeden önce alıcınızın çalıştığını doğrulayabilirsiniz.

Sonuç, diğer teslimatlar gibi Webhooks geçmişinde görünür.

Endpoint Gereksinimleri

Requirement	Detail
Scheme	Yalnızca `https://` — `http://` reddedilir
Host	Genel olarak çözümlenebilir olmalıdır. Özel, loopback, link-local ve CGNAT adresleri reddedilir
Response	Herhangi bir `2xx` durumu başarı sayılır
Timeout	Yanıt vermek için 10 saniyeniz var
Redirects	Takip edilmez. Bir `3xx` başarısızlık sayılır
Limit	Sunucu başına en fazla 5 endpoint

Host kontrolü hem endpoint'i kaydettiğinizde hem de her teslimattan önce yapılır; bu yüzden sonradan dahili bir adrese çözülmeye başlayan bir alan adına teslimat durur.

İstek

Her teslimat, JSON gövdeli bir POST isteğidir.

Başlıklar

Header	Example	Meaning
`Content-Type`	`application/json`	Her zaman JSON
`User-Agent`	`TicketWave-Webhooks/1.0.5`	Bunu gönderen bot sürümü
`X-TicketWave-Event`	`ticket.created`	Etkinlik türü
`X-TicketWave-Delivery`	`wh_3f2a…`	Bu teslimat için benzersiz kimlik
`X-TicketWave-Timestamp`	`1786224191`	Unix saniyesi, imzanın bir parçası
`X-TicketWave-Signature`	`sha256=9f86d0…`	İsteğin HMAC'i

Gövde

Her yük aynı zarf yapısını kullanır. Yalnızca data, etkinlik türüne göre değişir:

{
  "event": "ticket.created",
  "timestamp": "2026-08-26T08:23:11.000Z",
  "guild_id": "123456789012345678",
  "data": {
    "ticket_id": "ticket-1042",
    "ticket_num_id": 1042,
    "channel_id": "998877665544332211",
    "category": "🤖 Support",
    "user": { "id": "987654321098765432", "username": "Luna" },
    "created_at": "2026-08-26T08:23:11.000Z"
  }
}

Her türün data nesnesi için Event Reference sayfasına bakın.

İmzayı Doğrulama

Endpoint URL'nizi keşfeden herkes ona bir POST isteği gönderebilir. İmza, gerçek bir TicketWave teslimatını sahte bir teslimattan ayırmanızı sağlar.

Her zaman doğrulayın. Sisteminizde bir şey oluşturan veya kapatan doğrulanmamış bir endpoint, açık bir kapıdır.

İmza nasıl oluşturulur

TicketWave, zaman damgası ile ham istek gövdesini bir nokta ile birleştirir ve sonucu endpoint gizli anahtarınızı kullanarak HMAC-SHA256 ile işler:

signed_payload = X-TicketWave-Timestamp + "." + raw_request_body
signature      = HMAC_SHA256(signed_payload, your_endpoint_secret)

Başlık, bu özeti hex olarak kodlanmış ve öneklenmiş halde taşır: sha256=<digest>.

Alıcınızın yapması gerekenler

Ham gövdeyi okuyun. Doğrulamayı aldığınız tam baytlar üzerinden yapın. Eğer framework'ünüz önce JSON'u ayrıştırır ve siz onu yeniden serileştirirseniz, anahtar sırası veya boşluklar değişebilir ve özet eşleşmez.

HMAC'i yeniden hesaplayın: timestamp + "." + rawBody üzerinde, gizli anahtarınızla.

Sabit zamanda karşılaştırın (crypto.timingSafeEqual Node'da). Düz bir === zamanlama bilgisi sızdırır.

Zaman damgasını kontrol edin ve güncel olduğundan emin olun — beş dakikalık tolerans iyi bir varsayılandır. Zaman damgası imzalı yükün içindedir, bu yüzden saldırgan eski bir isteği yeni bir zaman damgasıyla yeniden oynatamaz.

Eksiksiz bir uygulama Example Server sayfasında yer alır.

Yeniden Denemeler

Başarısız olan bir teslimat otomatik olarak yeniden denenir.


Attempts	3 (ilk deneme + 2 yeniden deneme)
Backoff	1 saniye, ardından 5 saniye
Retried on	Ağ hataları, zaman aşımı, `408`, `429` ve tüm `5xx`
Not retried on	Diğer tüm `4xx` — bunlar endpoint'in isteği bilerek reddettiği anlamına gelir

Yeniden denemeler nedeniyle endpoint'iniz aynı etkinliği iki kez alabilir. X-TicketWave-Delivery değerini bir idempotency anahtarı olarak kullanın: işlediğiniz kimlikleri hatırlayın ve tekrarları yok sayın.

Teslimatlar sıralı değildir. Aynı anda iki bilet oluşturulursa, istekler herhangi bir sırada gelebilir — sıra sizin için önemliyse gövdedeki timestamp alanını kullanın.

Teslimat Geçmişi

Panelin Webhooks sayfası, her teslimatı durumu, yanıt kodu, süresi ve deneme sayısıyla birlikte listeler. Gönderilen tam istek yükünü ve sunucunuzun döndürdüğü yanıtı görmek için bir satırı açın.

Başarısız teslimatlar, detay sayfasından Retry Webhook ile yeniden gönderilebilir. Orijinal yükü aynı endpoint'e tekrar gönderir ve yeni bir teslimat kaydeder.

Geçmiş 30 gün boyunca saklanır, ardından otomatik olarak temizlenir.

Sorun Giderme

Problem	Fix
Endpoint kaydedilemiyor	URL `https://` olmalı ve genel bir adrese çözülmeli
Her şey yanıt kodu olmadan başarısız görünüyor	İstek size hiç ulaşmadı — zaman aşımı, DNS hatası veya bağlantı reddedildi
İmza asla eşleşmiyor	Ayrıştırılmış gövdeyi değil ham baytları hash'liyorsunuz ya da `timestamp + "."` önekini unuttunuz
Teslimatlar bir süre sonra duruyor	Sunucunuzun `4xx` döndürmeye başlayıp başlamadığını kontrol edin — bunlar yeniden denenmez
Bir etkinlik hiç gelmiyor	Endpoint o türe abone değil ya da sunucu premium'u kaybetti
Yinelenen etkinlikler	Yeniden denemelerde beklenir — `X-TicketWave-Delivery` ile tekilleştirin

Sonraki Adımlar

Event Reference (Her etkinlik ve yükü)
Example Server (Çalıştırılabilir bir Express alıcısı)
Log Channels (Aynı etkinlikler, ancak Discord'a gönderilir)

Genel Bakış