API Webhook
Descrizione
I webhook permettono a FattureWeb di notificare automaticamente al software del cliente alcuni eventi importanti, senza obbligare il cliente a interrogare periodicamente le API.
Quando si verifica un evento, ad esempio il cambio stato di una fattura o la ricezione
di una fattura passiva, FattureWeb invia una richiesta POST in formato JSON
all'URL registrato dal cliente.
Eventi disponibili
fattura.stato_aggiornato: lo stato di una fattura attiva è stato aggiornato.fattura.scartata: la fattura è stata scartata.fattura.consegnata: la fattura è stata consegnata.fattura.mancata_consegna: la fattura non è stata consegnata al destinatario.fattura.decorrenza_termini: la fattura ha raggiunto la decorrenza termini.fattura.accettata_pa: la fattura verso PA è stata accettata.fattura.rifiutata_pa: la fattura verso PA è stata rifiutata.fattura_passiva.ricevuta: è stata ricevuta una fattura passiva.
Payload inviato
Ogni webhook viene inviato tramite richiesta POST con body JSON.
{
"event_id": "evt_20260515163625_4466fbb0bcd9c3ff23c4dd09",
"event_type": "fattura.stato_aggiornato",
"created_at": 1778855788,
"data": {
"id_sdi": "123456789",
"nome_file": "IT01234567890_00001.xml",
"piva_mittente": "IT01234567890",
"piva_destinatario": "IT12345678901",
"stato": "CONSEGNATA",
"codice_errore": "",
"messaggio": "Fattura consegnata",
"data_evento": "2026-05-15T16:35:48+02:00"
}
}
Header inviati
Ogni richiesta contiene alcuni header utili per identificare e verificare il webhook:
X-FattureWeb-Event: evt_20260515163625_4466fbb0bcd9c3ff23c4dd09
X-FattureWeb-Event-Type: fattura.stato_aggiornato
X-FattureWeb-Timestamp: 1778855788
X-FattureWeb-Signature: sha256=...
Importante: il secret generato in fase di registrazione serve al cliente per verificare
la firma del webhook. Non deve essere condiviso pubblicamente e non viene mai inviato nel payload.