Ricevi gli eventi di TicketWave come richieste HTTP firmate nella tua applicazione.

Webhooks

Un webhook è una richiesta HTTP che TicketWave ti invia. Ogni volta che succede qualcosa nel tuo server — si apre un ticket, un membro viene inserito nella blacklist — TicketWave invia un POST con un corpo JSON a un URL che controlli tu.

Questa è la differenza rispetto ai Canali di log: i canali di log scrivono un embed in Discord da leggere per gli esseri umani, mentre i webhook consegnano l'evento grezzo al tuo codice.

I webhook sono una funzionalità premium. Senza premium, non è possibile creare endpoint e non vengono recapitati eventi.

Crea un endpoint

Apri la pagina degli endpoint

Dashboard del server → Webhooks → Endpoints.

Aggiungi un endpoint

Fai clic su Add Endpoint e compila due campi:

Field	Description
Endpoint URL	L'URL `https://` che riceve le richieste
Event Types	Quali eventi deve ricevere questo endpoint

Un endpoint riceve solo i tipi che selezioni. Non è consentito non selezionarne nessuno: scegline almeno uno.

Copia il secret di firma

TicketWave genera un secret di firma (whsec_…) nel momento in cui viene creato l'endpoint. Apri l'elenco degli endpoint, rivelalo con l'icona a forma di occhio e copialo nella configurazione della tua applicazione.

Tratta il secret come una password. Chiunque lo possieda può falsificare richieste che superano il controllo della firma. Conservalo in una variabile d'ambiente, mai nel tuo repository.

Invia un evento di test

Usa il pulsante Send test event (l'aeroplanino di carta) nella riga dell'endpoint. Invia una richiesta reale, completamente firmata, con "test": true nel payload, così puoi verificare che il tuo ricevitore funzioni prima che un ticket reale dipenda da esso.

Il risultato compare nella cronologia dei Webhooks come qualsiasi altra consegna.

Requisiti dell'endpoint

Requirement	Detail
Scheme	Solo `https://` — `http://` viene rifiutato
Host	Deve essere risolvibile pubblicamente. Indirizzi privati, loopback, link-local e CGNAT vengono rifiutati
Response	Qualsiasi stato `2xx` conta come successo
Timeout	Hai 10 secondi per rispondere
Redirects	Non vengono seguiti. Un `3xx` conta come fallimento
Limit	Fino a 5 endpoint per server

Il controllo dell'host avviene sia quando salvi l'endpoint sia prima di ogni singola consegna, quindi un dominio che in seguito inizia a risolversi verso un indirizzo interno smette di ricevere consegne.

La richiesta

Ogni consegna è un POST con un corpo JSON.

Headers

Header	Example	Meaning
`Content-Type`	`application/json`	Sempre JSON
`User-Agent`	`TicketWave-Webhooks/1.0.5`	La versione del bot che l'ha inviata
`X-TicketWave-Event`	`ticket.created`	Il tipo di evento
`X-TicketWave-Delivery`	`wh_3f2a…`	ID univoco di questa consegna
`X-TicketWave-Timestamp`	`1786224191`	Secondi Unix, parte della firma
`X-TicketWave-Signature`	`sha256=9f86d0…`	HMAC della richiesta

Body

Ogni payload usa lo stesso envelope. Solo data cambia in base al tipo di evento:

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

Consulta la Riferimento eventi per l'oggetto data di ogni tipo.

Verificare la firma

Chiunque scopra l'URL del tuo endpoint può inviargli una richiesta POST. La firma è il modo in cui distingui una consegna reale di TicketWave da una falsificata.

Verifica sempre. Un endpoint non verificato che crea o chiude elementi nel tuo sistema è una porta aperta.

Come viene costruita la firma

TicketWave unisce il timestamp e il corpo grezzo della richiesta con un punto, e applica HMAC-SHA256 al risultato usando il secret del tuo endpoint:

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

L'header contiene quel digest codificato in esadecimale e con prefisso: sha256=<digest>.

Cosa deve fare il tuo ricevitore

Leggi il corpo grezzo. Verifica usando i byte esatti che hai ricevuto. Se il tuo framework analizza prima il JSON e poi lo ri-serializzi, l'ordine delle chiavi o gli spazi possono cambiare e il digest non corrisponderà.

Ricalcola l'HMAC su timestamp + "." + rawBody con il tuo secret.

Confronta in tempo costante (crypto.timingSafeEqual in Node). Un semplice === rivela informazioni sul timing.

Controlla che il timestamp sia recente — cinque minuti di tolleranza sono un buon valore predefinito. Il timestamp è dentro il payload firmato, quindi un attaccante non può riprodurre una richiesta vecchia con un timestamp nuovo.

Un'implementazione completa è disponibile nella pagina Example Server.

Retry

Una consegna che fallisce viene ritentata automaticamente.


Attempts	3 (il primo tentativo più 2 retry)
Backoff	1 secondo, poi 5 secondi
Retried on	Errori di rete, timeout, `408`, `429` e qualsiasi `5xx`
Not retried on	Tutti gli altri `4xx` — significano che il tuo endpoint ha rifiutato la richiesta di proposito

A causa dei retry, il tuo endpoint può ricevere lo stesso evento due volte. Usa X-TicketWave-Delivery come chiave di idempotenza: memorizza gli ID che hai già elaborato e ignora i duplicati.

Le consegne non sono ordinate. Se due ticket vengono creati nello stesso momento, le richieste possono arrivare in qualsiasi ordine — usa il campo timestamp nel corpo se per te l'ordine è importante.

Cronologia delle consegne

La pagina Webhooks della dashboard elenca ogni consegna con il suo stato, il codice di risposta, la durata e il numero di tentativi. Apri una riga per vedere il payload esatto della richiesta inviata e la risposta restituita dal tuo server.

Le consegne fallite possono essere reinviate dalla pagina dei dettagli con Retry Webhook. Invia di nuovo il payload originale allo stesso endpoint e registra una nuova consegna.

La cronologia viene conservata per 30 giorni, poi viene pulita automaticamente.

Risoluzione dei problemi

Problem	Fix
L'endpoint non può essere salvato	L'URL deve essere `https://` e risolversi a un indirizzo pubblico
Tutto risulta fallito senza codice di risposta	La richiesta non ti è mai arrivata — timeout, errore DNS o connessione rifiutata
La firma non corrisponde mai	Stai calcolando l'hash sul corpo analizzato invece che sui byte grezzi, oppure hai dimenticato il prefisso `timestamp + "."`
Le consegne si fermano dopo un po'	Controlla se il tuo host ha iniziato a restituire `4xx` — non vengono ritentati
Un evento non arriva mai	L'endpoint non è iscritto a quel tipo, oppure il server ha perso il premium
Eventi duplicati	Attesi nei retry — deduplica su `X-TicketWave-Delivery`

Prossimi passi

Riferimento eventi (Ogni evento e il suo payload)
Example Server (Un ricevitore Express eseguibile)
Canali di log (Gli stessi eventi, ma pubblicati in Discord)

Panoramica