Vastaanota TicketWave-tapahtumat allekirjoitettuina HTTP-pyyntöinä omassa sovelluksessasi.

Webhookit

Webhook on HTTP-pyyntö, jonka TicketWave lähettää sinulle. Aina kun palvelimellasi tapahtuu jotain — tiketti avataan, jäsen joutuu mustalle listalle — TicketWave tekee POST-pyynnön JSON-rungolla sinun omistamaasi URL-osoitteeseen.

Tämä on ero Lokikanaviin: lokikanavat kirjoittavat Discordiin embedin ihmisten luettavaksi, webhookit välittävät raakatapahtuman suoraan koodillesi.

Webhookit ovat premium-ominaisuus. Ilman premiumia päätepisteitä ei voi luoda eikä tapahtumia toimiteta.

Luo päätepiste

Avaa päätepistesivu

Palvelimen hallintapaneeli → Webhooks → Endpoints.

Lisää päätepiste

Klikkaa Add Endpoint ja täytä kaksi kenttää:

Field	Description
Endpoint URL	`https://`-osoite, joka vastaanottaa pyynnöt
Event Types	Mitkä tapahtumat tämän päätepisteen pitäisi vastaanottaa

Päätepiste vastaanottaa vain ne tyypit, jotka valitset. Mitään ei saa jättää valitsematta — valitse vähintään yksi.

Kopioi allekirjoitussalaisuus

TicketWave luo allekirjoitussalaisuuden (whsec_…) heti, kun päätepiste luodaan. Avaa päätepisteiden lista, paljasta se silmäkuvakkeella ja kopioi se sovelluksesi asetuksiin.

Käsittele salaisuutta kuin salasanaa. Kuka tahansa, jolla se on, voi väärentää pyyntöjä, jotka läpäisevät allekirjoitustarkistuksesi. Säilytä se ympäristömuuttujassa, älä koskaan repositoriossasi.

Lähetä testitapahtuma

Käytä päätepisterivillä olevaa Send test event -painiketta (paperilentokone). Se toimittaa oikean, täysin allekirjoitetun pyynnön, jonka hyötykuormassa on "test": true, joten voit varmistaa vastaanottimesi toimivuuden ennen kuin oikea tiketti riippuu siitä.

Tulos näkyy Webhooks-historiassa kuten mikä tahansa muu toimitus.

Päätepisteen vaatimukset

Requirement	Detail
Scheme	Vain `https://` — `http://` hylätään
Host	Täytyy olla julkisesti ratkaistavissa. Yksityiset, loopback-, link-local- ja CGNAT-osoitteet hylätään
Response	Mikä tahansa `2xx`-tila lasketaan onnistumiseksi
Timeout	Sinulla on 10 sekuntia aikaa vastata
Redirects	Ei seurata. `3xx` lasketaan epäonnistumiseksi
Limit	Enintään 5 päätepistettä per palvelin

Host-tarkistus tehdään sekä silloin, kun tallennat päätepisteen että ennen jokaista yksittäistä toimitusta, joten domain, joka myöhemmin alkaa ratkaistua sisäiseen osoitteeseen, lakkaa saamasta toimituksia.

Pyyntö

Jokainen toimitus on POST-pyyntö JSON-rungolla.

Otsikot

Header	Example	Meaning
`Content-Type`	`application/json`	Aina JSON
`User-Agent`	`TicketWave-Webhooks/1.0.5`	Sen lähettäneen botin versio
`X-TicketWave-Event`	`ticket.created`	Tapahtuman tyyppi
`X-TicketWave-Delivery`	`wh_3f2a…`	Tämän toimituksen yksilöllinen tunniste
`X-TicketWave-Timestamp`	`1786224191`	Unix-sekunteina, osa allekirjoitusta
`X-TicketWave-Signature`	`sha256=9f86d0…`	Pyynnön HMAC

Runko

Jokainen hyötykuorma käyttää samaa kehystä. Vain data vaihtelee tapahtumatyypin mukaan:

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

Katso Event Reference saadaksesi jokaisen tyypin data-objektin.

Allekirjoituksen varmistaminen

Kuka tahansa, joka saa selville päätepisteesi URL-osoitteen, voi lähettää siihen POST-pyynnön. Allekirjoitus kertoo, onko kyseessä oikea TicketWave-toimitus vai väärennetty pyyntö.

Varmista aina. Varmistamaton päätepiste, joka luo tai sulkee asioita järjestelmässäsi, on avoin ovi.

Miten allekirjoitus muodostetaan

TicketWave yhdistää aikaleiman ja raakan pyynnön rungon pisteellä, ja ajaa tulokselle HMAC-SHA256:n käyttäen päätepisteesi salaisuutta:

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

Otsikko sisältää tämän tiivisteen heksakoodattuna ja etuliitteellä: sha256=<digest>.

Mitä vastaanottimesi täytyy tehdä

Lue raaka runko. Varmista vastaanotettuja täsmällisiä bittejä vasten. Jos frameworkisi parsii JSONin ensin ja serialisoit sen uudelleen, avainten järjestys tai välilyönnit voivat muuttua eikä tiiviste enää täsmää.

Laske HMAC uudelleen käyttäen timestamp + "." + rawBody ja salaisuuttasi.

Vertaa vakioajassa (crypto.timingSafeEqual Nodessa). Tavallinen === vuotaa ajoitustietoa.

Tarkista, että aikaleima on tuore — viiden minuutin toleranssi on hyvä oletus. Aikaleima on allekirjoitetussa hyötykuormassa, joten hyökkääjä ei voi toistaa vanhaa pyyntöä uudella aikaleimalla.

Täydellinen toteutus löytyy Example Server -sivulta.

Uusintayritykset

Epäonnistunut toimitus yritetään automaattisesti uudelleen.


Attempts	3 (ensimmäinen yritys + 2 uusintayritystä)
Backoff	1 sekunti, sitten 5 sekuntia
Retried on	Verkko-ongelmat, aikakatkaisut, `408`, `429` ja kaikki `5xx`
Not retried on	Kaikki muut `4xx` — ne tarkoittavat, että päätepisteesi hylkäsi pyynnön tarkoituksella

Uusintayritysten vuoksi päätepisteesi voi vastaanottaa saman tapahtuman kahdesti. Käytä X-TicketWave-Delivery-arvoa idempotenssiavaimena: muista käsitellyt tunnisteet ja ohita toistot.

Toimitukset eivät ole järjestyksessä. Jos kaksi tikettiä luodaan samalla hetkellä, pyynnöt voivat saapua kummassa tahansa järjestyksessä — käytä rungon timestamp-kenttää, jos järjestyksellä on sinulle väliä.

Toimitushistoria

Hallintapaneelin Webhooks-sivu listaa jokaisen toimituksen sen tilan, vastauskoodin, keston ja yritysten määrän kanssa. Avaa rivi nähdäksesi täsmällisen lähetetyn pyynnön hyötykuorman ja vastauksen, jonka palvelimesi palautti.

Epäonnistuneet toimitukset voidaan lähettää uudelleen yksityiskohtasivulta painikkeella Retry Webhook. Se lähettää alkuperäisen hyötykuorman uudelleen samaan päätepisteeseen ja kirjaa uuden toimituksen.

Historia säilytetään 30 päivää, minkä jälkeen se siivotaan automaattisesti.

Vianmääritys

Problem	Fix
Päätepistettä ei voi tallentaa	URL-osoitteen täytyy olla `https://` ja ratkaistua julkiseen osoitteeseen
Kaikki näkyy epäonnistuneena ilman vastauskoodia	Pyyntö ei koskaan saavuttanut sinua — aikakatkaisu, DNS-virhe tai yhteys evättiin
Allekirjoitus ei koskaan täsmää	Lasket hajautuksen parsitusta rungosta raakojen bittien sijaan, tai unohdit `timestamp + "."` -etuliitteen
Toimitukset loppuvat jonkin ajan kuluttua	Tarkista, alkoiko hostisi palauttaa `4xx`-vastauksia — niitä ei yritetä uudelleen
Tapahtuma ei koskaan saavu	Päätepiste ei ole tilannut kyseistä tyyppiä, tai palvelimelta katosi premium
Kaksoistapahtumat	Odotettavissa uusintayrityksissä — poista duplikaatit `X-TicketWave-Delivery`-arvon perusteella

Seuraavat askeleet

Event Reference (Jokainen tapahtuma ja sen hyötykuorma)
Example Server (Ajettava Express-vastaanotin)
Log Channels (Samat tapahtumat, mutta lähetetty Discordiin)

Yleiskatsaus