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.