Ta emot TicketWave-händelser som signerade HTTP-förfrågningar i din egen applikation.

Webhooks

En webhook är en HTTP-förfrågan som TicketWave skickar till dig. Varje gång något händer i din server — en ticket öppnas, en medlem svartlistas — gör TicketWave en POST med en JSON-body till en URL som du äger.

Det är skillnaden mot Log Channels: log channels skriver in en embed i Discord för människor att läsa, medan webhooks skickar den råa händelsen till din kod.

Webhooks är en premium-funktion. Utan premium kan endpoints inte skapas och inga händelser levereras.

Skapa en endpoint

Öppna sidan för endpoints

Serverdashboard → Webhooks → Endpoints.

Lägg till en endpoint

Klicka på Add Endpoint och fyll i två fält:

Field	Description
Endpoint URL	`https://`-URL:en som tar emot förfrågningarna
Event Types	Vilka händelser den här endpointen ska ta emot

En endpoint tar bara emot de typer du markerar. Det är inte tillåtet att välja inga alls — välj minst en.

Kopiera signeringshemligheten

TicketWave genererar en signeringshemlighet (whsec_…) i samma ögonblick som endpointen skapas. Öppna listan över endpoints, visa den med ögonikonen och kopiera den till din applikations konfiguration.

Behandla hemligheten som ett lösenord. Den som har den kan förfalska förfrågningar som klarar din signaturkontroll. Förvara den i en miljövariabel, aldrig i ditt repository.

Skicka en testhändelse

Använd knappen Send test event (pappersflygplanet) på raden för endpointen. Den levererar en riktig, fullt signerad förfrågan med "test": true i payloaden, så att du kan bekräfta att din mottagare fungerar innan en riktig ticket är beroende av den.

Resultatet visas i Webhooks-historiken precis som vilken annan leverans som helst.

Krav för endpointen

Requirement	Detail
Scheme	Endast `https://` — `http://` avvisas
Host	Måste kunna lösas publikt. Privata adresser, loopback, link-local och CGNAT-adresser nekas
Response	Vilken `2xx`-status som helst räknas som lyckad
Timeout	Du har 10 sekunder på dig att svara
Redirects	Följs inte. En `3xx` räknas som ett fel
Limit	Upp till 5 endpoints per server

Host-kontrollen görs både när du sparar endpointen och före varje enskild leverans, så en domän som senare börjar lösas till en intern adress slutar få leveranser.

Förfrågan

Varje leverans är en POST med en JSON-body.

Headers

Header	Example	Meaning
`Content-Type`	`application/json`	Alltid JSON
`User-Agent`	`TicketWave-Webhooks/1.0.5`	Botversionen som skickade den
`X-TicketWave-Event`	`ticket.created`	Händelsetypen
`X-TicketWave-Delivery`	`wh_3f2a…`	Unikt id för den här leveransen
`X-TicketWave-Timestamp`	`1786224191`	Unix-sekunder, del av signaturen
`X-TicketWave-Signature`	`sha256=9f86d0…`	HMAC för förfrågan

Body

Varje payload använder samma envelope. Endast data skiljer sig mellan händelsetyperna:

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

Se Event Reference för data-objektet för varje typ.

Verifiera signaturen

Alla som upptäcker din endpoint-URL kan skicka en POST-förfrågan till den. Signaturen är hur du skiljer en riktig TicketWave-leverans från en förfalskad.

Verifiera alltid. En overifierad endpoint som skapar eller stänger saker i ditt system är en öppen dörr.

Hur signaturen byggs

TicketWave slår ihop tidsstämpeln och den råa förfrågningsbody:n med en punkt, och kör HMAC-SHA256 över resultatet med din endpoint-hemlighet:

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

Headern innehåller det digestet hex-kodat och med prefix: sha256=<digest>.

Vad din mottagare måste göra

Läs den råa body:n. Verifiera mot exakt de bytes du tog emot. Om ditt ramverk först parsar JSON och du serialiserar om det, kan nyckelordning eller mellanrum ändras och digestet kommer inte att matcha.

Beräkna om HMAC över timestamp + "." + rawBody med din hemlighet.

Jämför i konstant tid (crypto.timingSafeEqual i Node). En vanlig === läcker timinginformation.

Kontrollera att tidsstämpeln är färsk — fem minuters tolerans är en bra standard. Tidsstämpeln finns i den signerade payloaden, så en angripare kan inte spela upp en gammal förfrågan med en ny tidsstämpel.

En komplett implementation finns på sidan Example Server.

Försök igen

En leverans som misslyckas försöks automatiskt igen.


Attempts	3 (första försöket plus 2 omförsök)
Backoff	1 sekund, sedan 5 sekunder
Retried on	Nätverksfel, timeouts, `408`, `429` och alla `5xx`
Not retried on	Alla andra `4xx` — de betyder att din endpoint avvisade förfrågan medvetet

På grund av omförsök kan din endpoint få samma händelse två gånger. Använd X-TicketWave-Delivery som en idempotency key: kom ihåg de id:n du redan har behandlat och ignorera upprepningar.

Leveranser är inte ordnade. Om två tickets skapas samtidigt kan förfrågningarna komma i vilken ordning som helst — använd fältet timestamp i body:n om ordningen spelar roll för dig.

Leveranshistorik

Dashboardens sida Webhooks listar varje leverans med dess status, svarskod, varaktighet och antal försök. Öppna en rad för att se den exakta request-payloaden som skickades och svaret som din server returnerade.

Misslyckade leveranser kan skickas igen från detaljsidan med Retry Webhook. Den skickar originalpayloaden igen till samma endpoint och registrerar en ny leverans.

Historiken sparas i 30 dagar, och rensas sedan automatiskt.

Felsökning

Problem	Fix
Endpointen kan inte sparas	URL:en måste vara `https://` och kunna lösas till en publik adress
Allt visas som misslyckat utan någon svarskod	Förfrågan nådde aldrig fram till dig — timeout, DNS-fel eller connection refused
Signaturen matchar aldrig	Du hashar den parsade body:n i stället för de råa bytesen, eller glömde prefixet `timestamp + "."`
Leveranser slutar efter ett tag	Kontrollera om din host började returnera `4xx` — de försöks inte igen
En händelse kommer aldrig fram	Endpointen prenumererar inte på den typen, eller så tappade servern premium
Dubbla händelser	Förväntat vid omförsök — deduplicera på `X-TicketWave-Delivery`

Nästa steg

Event Reference (Varje händelse och dess payload)
Example Server (En körbar Express-mottagare)
Log Channels (Samma händelser, men postade till Discord)

Översikt