Evento
Registrazione di una modifica relativa a pagamento, sessione di gioco, verifica KYC, bonus, profilo del giocatore o altro oggetto.
Documentazione / Webhook
Webhook e consegna degli eventi
Configura una trasmissione affidabile di stati ed eventi tra i sistemi: dalla creazione del messaggio e verifica della firma fino alla conferma della ricezione, alla riconsegna e al controllo degli errori.
Eventi
stati e modifiche
Firma
verifica dell'autenticità
Ripetizioni
riconsegna
Controllo
cronologia e diagnostica
Percorso dell'evento
Dalla creazione alla conferma
01
Creare l'evento
Indicare identificatore, tipo, ora, oggetto, stato e dati correlati.
02
Firmare e inviare
Trasmettere l'evento via HTTPS con firma e timeout limitato.
03
Confermare la ricezione
Dopo la verifica, salvare l'evento e restituire rapidamente una risposta HTTP di successo.
04
Ripetere in caso di errore
Ripetere la consegna aumentando l'intervallo e conservare gli eventi non inviati per l'analisi.
Panoramica
Il webhook comunica una variazione di stato
Il mittente può ripetere la consegna, quindi il destinatario deve verificare l'origine, confermare la ricezione e applicare ogni evento una sola volta.
Conferma
Il destinatario restituisce una risposta HTTP di successo dopo aver verificato e salvato in modo affidabile l'evento.
Ripristino
Il reinvio e la riconciliazione aiutano a ripristinare i dati dopo l'indisponibilità temporanea di uno dei sistemi.
Struttura dell'evento
Quali dati deve contenere un evento
Una struttura di messaggio uniforme semplifica verifica, routing, protezione dai duplicati e supporto di diversi tipi di evento.
Identificatore dell'evento
Valore univoco con cui il sistema riconosce una riconsegna e trova la cronologia di elaborazione.
Tipo di evento
Nome stabile e comprensibile che definisce la modifica avvenuta e il modo in cui deve essere elaborata.
Ora di creazione
Data e ora di creazione dell'evento in formato e fuso orario concordati.
Oggetto correlato
Tipo e identificatore di pagamento, giocatore, round, richiesta, bonus o altro oggetto.
Versione della struttura
Il numero di versione consente di modificare in sicurezza la struttura del messaggio senza interrompere le integrazioni esistenti.
Collegamento con l'operazione
Identificatore della richiesta originale, transazione, sessione o catena di azioni correlate.
Contesto
Brand, progetto, mercato, ambiente, provider e altri dati necessari per il corretto routing.
Dati dell'evento
Set minimo di campi per elaborare la modifica o effettuare una successiva richiesta API.
Firma e verifica
Verifica dell'autenticità e dell'integrità dell'evento
Prima di modificare i dati, il destinatario verifica connessione protetta, firma, ora di creazione e identificatore univoco dell'evento.
01
Ottenere il messaggio originale
Verificare la firma sul contenuto originale della richiesta prima di modificare il formato JSON.
02
Verificare l'ora
Rifiutare la richiesta se l'ora dell'evento è fuori dall'intervallo consentito.
03
Verificare la firma
Utilizzare il segreto concordato e l'algoritmo HMAC o la firma digitale.
04
Verificare l'identificatore
Assicurarsi che l'evento non sia già stato applicato e salvare il risultato della verifica.
Consegna e ripetizioni
Risposte HTTP e riconsegna
Il mittente deve distinguere tra ricezione riuscita, errore temporaneo e rifiuto permanente; il destinatario deve rispondere rapidamente e in modo univoco.
Risposta HTTP di successo
Conferma che l'evento è stato verificato e salvato in modo affidabile per l'elaborazione successiva.
Timeout limitato
Non eseguire elaborazioni lunghe prima di rispondere al mittente: salva prima l'evento.
Reinvio
Ripetere la consegna in caso di errore temporaneo di rete, indisponibilità o assenza di risposta.
Aumento dell'intervallo
Aumentare gradualmente la pausa tra i tentativi per evitare ulteriore carico.
Coda degli eventi non inviati
Dopo l'esaurimento dei tentativi, conservare l'evento per la diagnostica e l'elaborazione manuale.
Reinvio manuale
L'operatore può reinviare l'evento selezionato senza creare una nuova operazione.
Controllo della consegna
Monitorare numero di tentativi, risposte, ultimo errore e ora del prossimo invio.
Notifiche
Avvisare il team in caso di aumento degli errori, esaurimento dei tentativi e accumulo di eventi in coda.
Elaborazione degli eventi
Protezione dai duplicati e ordine degli stati
Il destinatario non deve fare affidamento su una sola consegna o su una sequenza rigorosa degli eventi.
Applicazione una sola volta
Salvare l'identificatore dell'evento prima di modificare i dati.
Confermare un evento ripetuto senza un nuovo addebito, accredito o modifica.
Collegare l'evento all'oggetto e al suo stato corrente.
Salvare l'evento e la modifica di business come un'unica operazione coerente.
Ordine e attualità
Confrontare ora, numero di sequenza o versione dell'evento.
Non riportare l'oggetto a uno stato obsoleto in caso di consegna ritardata.
Consentire solo transizioni di stato valide.
In caso di dubbio, richiedere lo stato corrente dell'oggetto tramite API.
Test
Cosa verificare prima del lancio
Verificare consegna riuscita, firma non valida, ripetizioni, risposta lenta, ordine degli eventi modificato e ripristino dopo un errore.
Firma non valida
Messaggio modificato, chiave sconosciuta, timestamp scaduto e algoritmo non supportato.
Riconsegna
Lo stesso evento arriva più volte prima e dopo il completamento dell'elaborazione.
Risposta lenta
Il destinatario risponde troppo lentamente, la connessione si interrompe oppure la conferma non raggiunge il mittente.
Ordine non corretto
Lo stato finale arriva prima di quello intermedio e un evento precedente viene consegnato dopo quello più recente.
Endpoint non disponibile
Verificare errori HTTP 5xx, DNS, TLS, rate limiting ed esaurimento completo dei tentativi.
Cronologia della consegna
Tramite l'identificatore dell'evento devono essere reperibili tutti i tentativi, le risposte, gli errori e il risultato dell'invio manuale.
Checklist prima del lancio
La consegna in produzione viene attivata dopo aver verificato sicurezza, protezione dai duplicati, reinvio e controllo degli errori.
Per gli ambienti di test e produzione vengono utilizzati endpoint e segreti di firma differenti.
La firma viene verificata sul messaggio originale tenendo conto dell'ora di creazione.
L'identificatore dell'evento viene salvato e protegge le operazioni dall'esecuzione ripetuta.
Il destinatario restituisce rapidamente una risposta HTTP di successo dopo aver salvato l'evento.
Sono configurati nuovi tentativi, aumento dell'intervallo e invio manuale.
La cronologia della consegna e la ricerca per identificatore sono disponibili al team di supporto.
Devi configurare una consegna affidabile degli eventi?
Fornisci l'elenco degli eventi, gli endpoint di ricezione e le regole di modifica degli stati. APIACE ti aiuterà a definire struttura dei messaggi, verifica della firma, riconsegna e controllo degli errori.