I webhook sono il metodo principale per ricevere notifiche in tempo reale dalla PSB. Ad ogni evento rilevante, una fattura ricevuta, una modifica di stato, una conferma di consegna, la PSB invia una richiesta HTTP POST al proprio endpoint con i dettagli dell'evento.

Si registra un webhook (un "hook") nella PSB con un URL e un topic. La PSB invia quindi tutti gli eventi di quel topic al proprio URL. Ogni evento contiene i dati rilevanti come payload JSON.

Registrare un hook tramite l'API:

POST /api/v1/hook

I principali elementi di configurazione:

Vuoi aggiungere un topic aggiuntivo (ad es. InvoiceReceived) a un hook esistente? Aggiorna la configurazione webhook esistente tramite la normale API /hook in modo che il topic desiderato sia incluso nell'array topics:

{
  "topics": ["InvoiceReceived"]
}

Aggiorna l'hook esistente invece di eliminarlo e ricrearlo. Eliminare e ricreare introduce una race condition in cui gli eventi potrebbero temporaneamente non essere consegnati (vedi l'avviso sopra).

MLS (Message Level Status) è il successore del precedente MLR e fornisce alla parte mittente un feedback sulla ricezione e l'elaborazione di un documento. L'MLS non è abilitato di default e deve essere configurato per party tramite la capability reviews nella configurazione SMP. Una volta abilitato, la PSB lo gestisce automaticamente: come Service Provider ricevente, la PSB invia un messaggio MLS al mittente dopo la ricezione e la consegna.

Quando si inviano documenti tramite la PSB, si riceve il feedback MLS dalla parte ricevente come evento webhook sul topic MessageLevelStatusReceived. Come Service Provider ricevente, segue un webhook separato con topic MessageLevelStatusSent non appena la PSB invia per proprio conto un MLS al SP mittente. Utilizzare questo topic per monitorare se le proprie risposte MLS auto-emesse vengono consegnate correttamente.

Il payload contiene tra l'altro:

Per ricevere messaggi MLS, l'hook Peppol deve contenere il campo mlsType. I valori possibili sono ALWAYS_SEND (inviare sempre MLS di ritorno) e FAILURE_ONLY (solo in caso di rifiuto).

Suggerimento: è possibile recuperare il documento MLS completo tramite GET /api/v1-beta/{partyId}/generic/{documentId}/download, ma il payload del webhook contiene generalmente informazioni sufficienti.

La PSB protegge tutte le consegne webhook con firme HMAC SHA256. Ad ogni richiesta la PSB invia l'header:

X-EConnect-Signature: sha256={handtekening}

Per verificare la firma:

1. Prendere il payload JSON grezzo dalla richiesta.
2. Calcolare l'hash HMAC SHA256 con la propria chiave segreta (la stessa fornita alla creazione dell'hook).
3. Confrontare l'hash calcolato con il valore nell'header X-EConnect-Signature.
4. Se corrispondono, la richiesta è autentica.

Controllare anche il campo sentOn nel payload. Se questo timestamp è più vecchio di 5 minuti, rifiutare la richiesta. Questo previene attacchi replay in cui una richiesta intercettata viene riprodotta successivamente.

Oltre alla verifica HMAC, la PSB offre livelli di sicurezza aggiuntivi:

• IP whitelisting: limitare le richieste in entrata agli IP di produzione PSB (104.40.188.59 e 104.47.148.207)
• Autenticazione OAuth per webhook: la PSB può autenticarsi presso il proprio endpoint con credenziali OAuth2
• Mutual SSL: utilizzare certificati client per l'autenticazione TLS reciproca

Se sono configurati più hook, la PSB determina quale hook utilizzare in base a:

1. Hook a livello di PartyId hanno precedenza sugli hook a livello di environment
2. Topic specifici hanno precedenza sui wildcard
3. Se più hook con filtri corrispondono allo stesso topic: vince il filtro più lungo (per numero di caratteri) -- ad esempio, un filtro con una clausola && aggiuntiva vince su un filtro più corto senza quella clausola. Questo evita la doppia consegna senza richiedere che i filtri siano reciprocamente esclusivi.
4. A parità di priorità: hook-id come criterio di spareggio

Oltre ai topic specifici, è possibile utilizzare anche pattern wildcard per intercettare più tipi di evento con un unico hook.

Di seguito sono riportati i problemi più comuni con i webhook e come risolverli.

Il PSB può ricevere una fattura d'acquisto senza inoltrarla alla parte destinataria. Il topic InvoiceReceived significa che il PSB ha ricevuto la fattura; senza un hook su quel topic, non viene inviato nulla a un endpoint.

• L'assenza di errori webhook non prova che l'hook funzioni. HookSentError esiste solo se è configurato un hook che non riesce a consegnare.
• Un hook potrebbe essere stato rimosso nel frattempo. Una precedente consegna riuscita alla stessa parte/endpoint prova che l'hook esisteva, non che sia ancora presente ora. Verificare quindi prima la configurazione attuale dell'hook invece di trattarlo come una prima configurazione.
• Una conferma di ricezione lato mittente non equivale alla consegna al software destinatario.

Correggere un hook mancante aggiornando l'hook esistente invece di eliminarlo e ricrearlo.

Il PSB invia eventi webhook (ad es. InvoiceReceived quando si riceve una fattura elettronica) all'endpoint configurato. Se l'endpoint non è raggiungibile - a causa di un timeout, un errore SSL o un errore DNS come No such host is known - il PSB riprova con backoff esponenziale per 5 giorni (timeout 100 sec. per tentativo). Ogni tentativo genera un evento HookSentRetry; dopo 5 giorni senza risposta 2xx, viene emesso HookSentError come stato finale e il PSB smette di riprovare.

Conseguenza: una fattura elettronica ricevuta non verrà consegnata al cliente finché l'endpoint è irraggiungibile, senza che il cliente se ne accorga direttamente. Azioni consigliate:

• Configurare il monitoraggio: sottoscrivere un hook (ad es. un mail-hook) al topic HookSentError in modo che un errore di consegna definitivo venga segnalato attivamente anziéé passare inosservato. Considerare anche HookSentRetry per il rilevamento precoce.
• Risolvere la causa principale: in caso di errore DNS, verificare e ripristinare il record DNS del dominio dell'endpoint; in caso di timeout, fare in modo che l'endpoint risponda più rapidamente (2xx entro 100 sec., elaborazione pesante in modo asincrono).
• Recuperare gli eventi mancati: gli eventi falliti durante l'interruzione possono essere recuperati tramite il batch endpoint. La finestra di 5 giorni significa che un recupero tempestivo entro tale periodo può ancora ripristinare la consegna normale.

Prima linea: interruzione lato cliente vs. problema tecnico (accettazione e produzione)

HookSentError, un HTTP 404 ripetuto o "endpoint offline"/"ambiente di accettazione spento" può anche derivare dal fatto che il cliente spegne temporaneamente l'endpoint di accettazione o produzione (sviluppo, manutenzione). Questo non è un incidente della piattaforma eConnect.

1. Confermare il sintomo: HookSentError, endpoint offline o HTTP 404 sull'endpoint webhook configurato dal cliente. Spesso visibile come il testo esatto Response status code does not indicate success: 404 (Not Found) (di solito una HttpRequestException .NET sulla richiesta hook in uscita). Si tratta di un 404 proveniente dall'endpoint stesso del cliente (spento o percorso errato), non dell'errore Peppol PartyId not found in fase di invio (404 SMP), né di un 404 di risorsa REST dalla gestione degli errori dell'API.
2. Chiedere se l'interruzione è intenzionale e temporanea (sviluppatori/cliente).
3. Confermato temporaneo → annotare, nessuna ulteriore azione lato eConnect finché l'endpoint non torna attivo. Non appena l'endpoint restituisce nuovamente 2xx, gli eventi mancati possono essere recuperati tramite il batch endpoint.
4. Non intenzionale o sconosciuto → seguire il runbook standard HookSentError sopra (DNS/SSL/timeout, log, monitoraggio, recupero batch).

• Utilizzare sempre HTTPS per il proprio endpoint webhook
• Implementare elaborazione idempotente: la PSB può in rari casi consegnare un evento più volte
• Restituire rapidamente un codice di stato 2xx: la PSB considera ogni risposta non 2xx come un errore e riproverà l'evento
• Registrare tutti gli eventi ricevuti per debugging e auditing
• Utilizzare un sistema a coda (queue) dalla propria parte se l'elaborazione richiede tempo: confermare prima la ricezione e poi elaborare