Webhook Verifica della firma e idempotenza
Segue questa pagina Agent Java SDK WEBHOOKS.md al commit fa6c7b6. Questo è un aggiornamento solo della documentazione; non è stato rilasciato alcun nuovo artefatto SDK contenente metodi di helper di avviso.
Tutti e quattro i tipi di eventi utilizzano una richiamata del commerciante URL e vengono inviati dall’organismo event. Vedere Webhook Eventi e avvisi di liquidazione per campi evento ed esempi di payload.
Webhook intestazioni
Idempotenza degli eventi
Deduplica persistente nell’ambito del commerciante e environment, atomicamente con l’elaborazione aziendale. Valori notificationId diversi identificano notifiche FIRST / UPGRADE / REMINDER indipendenti; non eliminare le notifiche raggruppandole per utente, episodio o eventType. Non è possibile utilizzare una chiave di idempotenza vuota per la deduplicazione. Il SDK restituisce solo una chiave di supporto; non persiste né elabora i dati aziendali. Registrare la stessa identità con un corpo diverso come conflitto; non sovrascrivere il corpo elaborato.
Verifica e ricezione della firma
Utilizza il segreto del commerciante API per calcolare la firma esadecimale HMAC-SHA256 di timestamp + nonce + rawBody. Verificare i byte originali ricevuti; non formattare prima JSON, rinominare i campi o riserializzare il corpo.
Verifica prima la firma, quindi controlla la finestra temporale (consigliata ±300 secondi), il commerciante e l’ambiente. Quindi estrai l’identità di idempotenza e gestisci la notifica in modo affidabile. Conservare valori di eventi sconosciuti per la diagnosi; non interpretarli mai come fondi di successo. L’assistente per la verifica non esegue controlli di finestra temporale, proprietà o deduplicazione persistente.
Restituisci HTTP 2xx dopo aver completato l’elaborazione o confermato un duplicato identico; restituisce non-2xx in caso di errore. Il mittente dell’avviso ha un timeout HTTP di 5 secondi e un massimo di 8 tentativi. I tentativi mantengono il corpo congelato; cambiano solo il timestamp della firma e il nonce. Rispondere tempestivamente dopo un’accettazione affidabile; il lavoro aziendale di lunga durata può utilizzare le attività persistenti del commerciante.
Le notifiche del commerciante non dipendono dallo stato online dell’utente. I push degli utenti della piattaforma sono solo consegne best-effort online, senza riproduzione offline; la fase uno non ha una casella di posta per le notifiche.
Risposte riuscite e interruzione dei tentativi
Le richiamate di fondi e gli avvisi di liquidazione utilizzano solo il codice di stato HTTP per determinare il successo della consegna. Il mittente non interpreta il corpo della risposta code, success, result o message e non richiede una risposta fissa OK / success.
Il corpo della risposta può essere vuoto, testo o JSON. I campi di esempio result sono informativi per il commerciante, non requisiti di protocollo. 202 Accepted interrompe anche i tentativi della piattaforma, quindi restituiscilo solo dopo aver salvato in modo affidabile la notifica nella coda delle attività persistenti del commerciante, non semplicemente avviando un’attività asincrona in memoria.
Esempi di risposte di successo
Una volta completata l’elaborazione aziendale o dopo che la notifica è stata salvata in modo affidabile nella coda in sospeso del commerciante:
Quando non è necessario alcun corpo di risposta:
Per una notifica già elaborata con un corpo identico, salta l’elaborazione aziendale duplicata e restituisci comunque 2xx:
Esempi di risposta al fallimento
Se il database è temporaneamente non disponibile e il commerciante non ha completato l’elaborazione né salvato la notifica in modo affidabile, restituisci non-2xx in modo che la piattaforma possa riprovare:
Rifiutare una firma non valida senza aggiornare i dati aziendali o i record di deduplicazione riuscita:
Questi organismi di risposta non modificano le decisioni sui nuovi tentativi. Non aspettarti che un 401 o 409 interrompa permanentemente i nuovi tentativi; indagare sulla firma, sul contenuto della notifica o sulla configurazione del commerciante.
Esempio errato: la seguente risposta conta comunque come consegna avvenuta con successo. La piattaforma non riproverà a causa di success:false.
Se il framework o il gestore delle eccezioni globali racchiude gli errori aziendali in HTTP 200, imposta esplicitamente lo stato di errore corretto sull’endpoint di callback.
Riconoscimento affidabile e consegna duplicata
Ordine consigliato: verificare la firma e controllare l’ora/il commerciante/l’ambiente → estrarre l’identità di idempotenza → elaborare i dati aziendali e i record di deduplicazione riusciti in una transazione oppure salvare in modo affidabile un’attività in sospeso → restituire 200/204 dopo che il commit ha avuto esito positivo. Non restituire 2xx né contrassegnare la notifica elaborata prima di una scrittura del database riuscita.
La consegna duplicata può ancora verificarsi dopo che l’elaborazione del commerciante ha avuto esito positivo: la risposta potrebbe andare persa o la piattaforma potrebbe ricevere 2xx ma non riuscire a persistere SUCCESS. HTTP le richiamate non garantiscono la consegna una tantum. Deduplicazione persistente all’interno del commerciante e dell’ambito environment. I fondi utilizzano orderType:orderId:targetStatus; gli avvisi utilizzano liquidation.warning:notificationId. Per un corpo identico già elaborato, restituire 2xx senza accreditare fondi o emettere nuovamente un sollecito. Per la stessa identità con un corpo diverso, registrare un conflitto e restituire non-2xx; non sovrascrivere il record originale.
Il successo della conferma significa che il commerciante ha ricevuto/elaborato la notifica, non che l’operazione di fondi è andata a buon fine. Dopo aver registrato una notifica di fondi valida con targetStatus=FAILED, restituisci anche 2xx; il fallimento dell’ordine non costituisce motivo per rifiutare la conferma della notifica.
Finanziamenti e confini ambientali
Il trasferimento del contratto originale webhook e il flusso queryOrder non si applicano automaticamente al finanziamento. Conferma le operazioni di finanziamento utilizzando queryWalletTransfer e l’ambiente dell’ordine originale. Utilizzi di finanziamento status; Le risposte originali al trasferimento del contratto utilizzano orderStatus. Una risposta HTTP o code=0 riuscita non dimostra di per sé che i fondi sono stati spostati.
Le notifiche esplicite di trasferimento del contratto simulato includono environment=SIMULATED. Verificare innanzitutto il corpo non elaborato, quindi verificare l’utente, l’importo, l’identità dell’ordine e l’ambiente rispetto all’ordine commerciale locale salvato.