Webhook in produzione

La sezione sui webhook copre le basi; questa è la checklist per la produzione.

Il contratto

• La consegna è at-least-once (almeno una volta) e senza ordine garantito. Elimina i duplicati in base all'id dell'evento e tratta data.object come lo stato attuale aggiornato, non come una differenza.
• Rispondi 2xx in fretta (metti in coda, poi elabora). Il timeout è di 10 s.
• Nuovi tentativi: 1m → 5m → 30m → 2h → 12h, poi la consegna è fallita.
• Dopo 20 errori consecutivi l'endpoint viene disattivato automaticamente. Lo vedi in Impostazioni → Sviluppatori → Webhook (riattivalo dopo aver risolto).

Verifica ogni consegna

Controlla X-Nembol-Signature (t=…,v1=…, HMAC-SHA256 di <t>.<raw body> con il secret del tuo endpoint). Il codice completo è in Verifica le firme. Durante la rotazione di un secret vengono inviate sia la vecchia sia la nuova firma per 24 ore.

Da sapere

• Usa il corpo grezzo della richiesta per l'HMAC. Qualsiasi riserializzazione invalida la firma.
• Hai perso qualche evento? Le consegne fallite si possono reinviare dalla dashboard (Webhook → consegne → Riconsegna), e GET /events è il tuo recupero: gli eventi vengono conservati 30 giorni.
• Gli endpoint devono essere HTTPS su un host pubblico: un nome di dominio (niente indirizzo IP, niente localhost, *.localhost, *.local o *.internal) che si risolve in un indirizzo pubblico. Un nome che si risolve in un indirizzo privato o interno viene rifiutato al momento della consegna (il tentativo fallisce).
• Prima fai una prova: Invia evento di prova nella dashboard chiama il tuo endpoint con un evento fittizio firmato. Collega la verifica della firma prima di andare in produzione.

Ultimo aggiornamento il 20 ottobre 2026