Webhook firmati HMAC per il ciclo di vita dell'off-ramp.
Quando il tuo prodotto ha bisogno dello stato del ciclo di vita in modo asincrono, registra gli endpoint webhook e verifica ogni consegna. La firma lega il timestamp all'esatto body grezzo, così puoi rifiutare payload manomessi o ripetuti.
Eventi del ciclo di vita
| Evento | Significato |
|---|---|
| deposit.created | Un deposito di vendita è stato creato su Base |
| deposit.partially_filled | Un deposito riempito in parte |
| deposit.filled | Un deposito riempito interamente |
| deposit.closed | Un venditore ha chiuso o prelevato il saldo residuo |
| otc.taken | Un deposito OTC privato è stato preso dall'acquirente approvato |
Verifica ogni consegna
- 1Leggi l'header X-Usdctofiat-Signature nel formato t=<unix>,v1=<hex>.
- 2Costruisci il payload firmato come la stringa timestamp.rawBody usando il body grezzo e non parsato.
- 3Calcola HMAC-SHA256 su quel payload con il segreto del tuo endpoint.
- 4Confronta in tempo costante con il valore hex v1 prima di fidarti dell'evento.
- 5Opzionalmente, rifiuta le consegne il cui timestamp è più vecchio della finestra che scegli.
La protezione dai replay è una tua scelta
Il ricevitore di riferimento nella repo degli starter considera obsoleti i timestamp più vecchi di 5 minuti per proteggersi dai replay. Quella finestra è applicata dal tuo verificatore, non dal mittente, quindi puoi restringerla o allargarla in base alla tua tolleranza di latenza e ritentativi.
Poiché la firma copre timestamp.rawBody, fai il parsing del JSON solo dopo che il controllo HMAC è passato. Verificare l'oggetto parsato invece dei byte grezzi è il modo più comune per sbagliare in modo sottile la verifica della firma.
Registra e opera
- Registra gli endpoint con la tua API key Peerlytics; una sola key autentica le superfici offramp e Peerlytics.
- Gli endpoint che accumulano ripetuti fallimenti di consegna consecutivi possono essere disabilitati finché non li sistemi.
- Usa il ricevitore della repo degli starter come riferimento HMAC noto e funzionante.
- Tratta i webhook come indizi di stato; riconciliali con la verità onchain tramite deposits() quando conta.
Keep exploring
Common questions
Come sono firmati i webhook di USDCtoFiat?
Ogni consegna porta X-Usdctofiat-Signature: t=<unix>,v1=<hex>, un HMAC-SHA256 sulla stringa timestamp.rawBody. Ricalcola l'HMAC con il segreto del tuo endpoint sul body grezzo e confronta in tempo costante prima di fidarti dell'evento.
Come prevengo i webhook ripetuti?
Rifiuta le consegne il cui timestamp firmato è più vecchio di una finestra che scegli tu. Il ricevitore di riferimento usa 5 minuti. Il mittente non impone alcuna finestra, quindi è responsabilità del tuo verificatore.
Mi serve una API key per i webhook?
Sì. Creare depositi è permissionless, ma registrare gli endpoint webhook richiede una API key Peerlytics. La stessa key autentica anche l'API Peerlytics.