Fogadj TicketWave eseményeket aláírt HTTP-kérésekként a saját alkalmazásodban.

Webhookok

A webhook egy HTTP-kérés, amelyet a TicketWave küld neked. Amikor valami történik a szervereden — megnyílik egy jegy, egy tag feketelistára kerül — a TicketWave egy JSON törzset POST-ol egy általad birtokolt URL-re.

Ez a különbség a Naplócsatornák és ez között: a naplócsatornák egy embedet írnak a Discordba, hogy az emberek elolvassák, a webhookok pedig a nyers eseményt adják át a kódodnak.

A webhookok prémium funkciók. Prémium nélkül nem hozhatók létre végpontok, és nem kézbesülnek események.

Végpont létrehozása

Nyisd meg a végpontok oldalát

Szerver irányítópult → Webhooks → Végpontok.

Adj hozzá egy végpontot

Kattints az Add Endpoint gombra, és töltsd ki a két mezőt:

Field	Description
Endpoint URL	Az a `https://` URL, amely fogadja a kéréseket
Event Types	Mely eseményeket kapja meg ez a végpont

Egy végpont csak azokat a típusokat kapja meg, amelyeket bejelölsz. Üresen hagyni nem lehet — legalább egyet válassz.

Másold ki az aláírási titkot

A TicketWave az endpoint létrehozásának pillanatában generál egy aláírási titkot (whsec_…). Nyisd meg a végpontok listáját, a szem ikonra kattintva jelenítsd meg, majd másold be az alkalmazásod konfigurációjába.

A titkot kezeld úgy, mint egy jelszót. Aki birtokolja, hamis kéréseket tud küldeni, amelyek átmennek az aláírás-ellenőrzésen. Tartsd környezeti változóban, soha ne a repódban.

Küldj teszteseményt

Használd a végpont sorában a Send test event gombot (a papírrepülőt). Egy valódi, teljesen aláírt kérést küld, a payloadban "test": true értékkel, így még azelőtt ellenőrizheted, hogy a fogadó működik, mielőtt egy éles jegy erre támaszkodna.

Az eredmény a Webhooks előzmények között jelenik meg, ugyanúgy, mint bármely más kézbesítés.

Végpontkövetelmények

Requirement	Detail
Scheme	Csak `https://` — a `http://` elutasításra kerül
Host	Nyilvánosan feloldhatónak kell lennie. Privát, loopback, link-local és CGNAT címek nem engedélyezettek
Response	Bármely `2xx` státusz sikernek számít
Timeout	10 másodperced van válaszolni
Redirects	Nem követi őket. A `3xx` hibának számít
Limit	Szerverenként legfeljebb 5 végpont

A hostellenőrzés akkor is lefut, amikor elmented a végpontot, és minden egyes kézbesítés előtt, így ha egy domain később belső címre kezd feloldódni, többé nem kap kézbesítést.

A kérés

Minden kézbesítés egy POST JSON törzzsel.

Fejlécek

Header	Example	Meaning
`Content-Type`	`application/json`	Mindig JSON
`User-Agent`	`TicketWave-Webhooks/1.0.5`	A bot verziója, amely elküldte
`X-TicketWave-Event`	`ticket.created`	Az esemény típusa
`X-TicketWave-Delivery`	`wh_3f2a…`	A kézbesítés egyedi azonosítója
`X-TicketWave-Timestamp`	`1786224191`	Unix másodpercekben, az aláírás része
`X-TicketWave-Signature`	`sha256=9f86d0…`	A kérés HMAC-je

Törzs

Minden payload ugyanazt a burkolót használja. Csak a data különbözik eseménytípusonként:

{
  "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"
  }
}

A Event Reference oldalon megtalálod minden típus data objektumát.

Az aláírás ellenőrzése

Bárki, aki megtudja a végpontod URL-jét, küldhet rá egy POST kérést. Az aláírás mutatja meg, hogy valódi TicketWave kézbesítésről van-e szó, vagy hamisítványról.

Mindig ellenőrizd. Egy ellenőrizetlen végpont, amely dolgokat hoz létre vagy zár le a rendszeredben, nyitott kapu.

Hogyan készül az aláírás

A TicketWave összefűzi az időbélyeget és a nyers kérés törzsét egy ponttal, majd HMAC-SHA256-ot futtat rajta a végpont titkoddal:

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

A fejléc ezt a kivonatot hexadecimálisan kódolva és előtaggal ellátva tartalmazza: sha256=<digest>.

Mit kell tennie a fogadónak

Olvasd be a nyers törzset. Az ellenőrzést pontosan az ellenőrzésre kapott bájtokkal végezd. Ha a keretrendszered előbb JSON-ná alakítja, majd újraszerializálod, a kulcsok sorrendje vagy a szóközök megváltozhatnak, és a kivonat nem fog egyezni.

Számold újra az HMAC-et a timestamp + "." + rawBody alapján a titkoddal.

Hasonlítsd össze konstans időben (crypto.timingSafeEqual Node-ban). Egy sima === időzítési információt szivárogtat.

Ellenőrizd, hogy az időbélyeg friss-e — az öt perc tolerancia jó alapértelmezés. Az időbélyeg az aláírt payload része, így egy támadó nem tud egy régi kérést friss időbélyeggel újrajátszani.

Egy teljes megvalósítás az Example Server oldalon található.

Újrapróbálkozások

A sikertelen kézbesítést a rendszer automatikusan újrapróbálja.


Attempts	3 (az első próbálkozás plusz 2 újrapróbálkozás)
Backoff	1 másodperc, majd 5 másodperc
Retried on	Hálózati hibák, időtúllépések, `408`, `429` és minden `5xx`
Not retried on	Minden más `4xx` — ezek azt jelentik, hogy a végpontod szándékosan elutasította a kérést

Az újrapróbálkozások miatt a végpontod ugyanazt az eseményt kétszer is megkaphatja. Használd az X-TicketWave-Delivery értékét idempotencia kulcsként: jegyezd meg a feldolgozott azonosítókat, és hagyd figyelmen kívül az ismétléseket.

A kézbesítések nincsenek sorrendben. Ha két jegy ugyanabban a pillanatban jön létre, a kérések bármilyen sorrendben megérkezhetnek — ha a sorrend fontos, használd a törzs timestamp mezőjét.

Kézbesítési előzmények

Az irányítópult Webhooks oldala felsorolja az összes kézbesítést az állapotával, válaszkódjával, időtartamával és a próbálkozások számával együtt. Nyiss meg egy sort, hogy lásd a pontosan elküldött kérés payloadját és a szervered válaszát.

A sikertelen kézbesítéseket a részletező oldalról újra lehet küldeni a Retry Webhook gombbal. Újra elküldi az eredeti payloadot ugyanarra a végpontra, és új kézbesítésként rögzíti.

Az előzmények 30 napig maradnak meg, utána automatikusan törlődnek.

Hibaelhárítás

Problem	Fix
A végpont nem menthető	Az URL-nek `https://` kell lennie, és nyilvános címre kell feloldódnia
Minden sikertelenként jelenik meg válaszkód nélkül	A kérés soha nem jutott el hozzád — időtúllépés, DNS-hiba vagy a kapcsolat elutasítva
Az aláírás soha nem egyezik	A feldolgozott törzset hash-eled a nyers bájtok helyett, vagy elfelejtetted a `timestamp + "."` előtagot
A kézbesítések egy idő után leállnak	Ellenőrizd, hogy a hostod nem kezdett-e `4xx` választ adni — azokat nem próbálja újra
Egy esemény soha nem érkezik meg	A végpont nincs feliratkozva arra a típusra, vagy a szerver elvesztette a prémiumot
Duplikált események	Újrapróbálkozásoknál várható — deduplikálj az `X-TicketWave-Delivery` alapján

Következő lépések

Event Reference (Minden esemény és a hozzá tartozó payload)
Example Server (Egy futtatható Express fogadó)
Log Channels (Ugyanezek az események, de a Discordba posztolva)

Áttekintés