Ricevere aggiornamenti delle fatture tramite webhook
Nella sezione di configurazione API nella piattaforma Free Invoice, è possibile configurare degli endpoint a cui saranno inoltrate notifiche di ad ogni aggiornamento di fattura (sia di costo che di ricavo). In altre parole, ad ogni modifica dello stato fattura (ad esempio da “Inviata” a “Consegnata”), Free Invoice invierà una chiamata HTTP all’endpoint specificato con tutti i dettagli della fattura. Questa è la soluzione ideale per chi vuole utilizzare le API di Free Invoice in e-commerce e siti web.
Per poter funzionare, l’e-commerce deve esporre una rotta HTTP raggiungibile pubblicamente in grado di accettare chiamate POST con body in formato JSON.
Se l’utente ha configurato un endpoint “https://mioecommerce.it/freeinvoicewebhooks” ad ogni aggiornamento di una fattura sarà fatta una richiesta POST del tipo:
| POST /invoiceId HTTP/ 1.1 Host: mioecommerce.it Content-Type: application/json x-freeinvoice-signature: cb5c4c6a2fa924e0848cd21b6935961d6851b9415d96ec8a…87c0a x-freeinvoice-timestamp: 1602575616 Content-Length: 690 { ” type ” : ” invoice_status_changed ” , ” data ” : { ” invoiceId ” : ” 12 ” , … } } |
NB: il campo “data” mostrato nell’esempio è identico al campo ricevuto in risposta alla richiesta dettagli fattura. Per maggiori dettagli vedere la sezione “Visualizza i dettagli di una fattura”.
Per verificare la chiamata ricevuta sono SEMPRE NECESSARIE le seguenti operazioni:
- assicurarsi che il timestamp UNIX ricevuto nell’header “x-freeinvoice-timestamp” non sia distante dal timestamp attuale del sistema di oltre 5 minuti. Al fine di verificare questa condizione, assicurarsi che l’orario del webserver sia aggiornato correttamente.
- assicurarsi che la firma del messaggio ricevuta nell’header “x-freeinvoice-signature” sia uguale a
| var timestamp = HEADER[‘x-freeinvoice-timestamp’] var payload = BODY var apiKey = ‘mia-api-key’ |
| hash_hmac(‘sha256’, ” { timestamp }.{ payload } “, apiKey); |
Se una delle due condizioni non è valida RIGETTARE la richiesta con HTTP status code diverso da 200. Per accettare la richiesta rispondere con HTTP status code 200.
NB: tutte le richieste rigettate saranno ritrasmesse ad intervalli regolari per tre giorni.