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