Errori webhook
Sintomo A: L'endpoint webhook restituisce 4xx/5xx
Come verificare: Dashboard → Proprietà → Webhook → Log consegne — mostra codici di stato e corpi delle risposte.
Cause e soluzioni:
| Codice di stato | Causa probabile | Soluzione |
|---|---|---|
401 | Verifica della firma fallita | Controlla il tuo codice di verifica — vedi Sicurezza webhook |
400 | Il tuo endpoint rifiuta il formato del payload | Registra il corpo grezzo e confronta con lo schema del payload |
404 | L'URL dell'endpoint è cambiato | Aggiorna l'URL del webhook in Proprietà → Webhook → [Webhook] → Modifica |
500 | Bug nel tuo gestore webhook | Controlla i log del server per l'errore |
timeout | Il tuo endpoint impiega troppo tempo a rispondere | Rispondi con 200 immediatamente, elabora in modo asincrono |
Sintomo B: Verifica della firma webhook fallita
Causa: Cause più comuni:
- Stringa di firma costruita in modo errato — deve essere
{timestamp}.{corpo_grezzo}(non JSON analizzato) - Utilizzo di un segreto diverso da quello mostrato nel Dashboard
- Lettura di un corpo bufferizzato/modificato anziché dei byte grezzi
Soluzione: Assicurati di leggere il corpo della richiesta grezzo prima di qualsiasi analisi JSON. In Express:
// DEVE usare il middleware per corpo grezzo
app.use('/webhooks', express.raw({ type: '*/*' }));
Sintomo C: Le consegne webhook sono ritardate
Causa: ConsentForge riprova le consegne fallite con backoff esponenziale — i ritardi sono previsti dopo i fallimenti iniziali.
Soluzione: Risolvi l'errore sottostante (vedi Sintomo A). Una volta che il tuo endpoint restituisce 2xx, le consegne future saranno immediate.
Sintomo D: Consegne mancanti — eventi non ricevuti
Come verificare: Confronta il conteggio del log di consegna del Dashboard con il conteggio ricevuto dal tuo server.
Causa: Alcuni eventi potrebbero aver esaurito tutti i tentativi di ripetizione (5 tentativi in ~2 ore).
Soluzione: Proprietà → Webhook → Log consegne → Filtra: Falliti — usa il pulsante Riproduci per reinviare le consegne fallite.