Perché l’endpoint webhook è stato disattivato?

Questo articolo spiega perché Emailit smette di inviare eventi a un webhook, come trovare l’errore all’origine e come recuperare gli eventi persi.

Sintomi

• Hai ricevuto un’email da Emailit che dice che il tuo webhook non funziona, e più tardi un’altra che dice che è stato disattivato.
• Il webhook risulta disattivato in Email API›Webhooks e i nuovi eventi non arrivano più al tuo endpoint.
• La scheda Requests nella pagina del webhook elenca richieste con stato Failed e molti tentativi.

Causa

Emailit considera riuscita qualsiasi risposta 2xx. Tutto il resto conta come errore, compresi:

• Codici di stato 4xx o 5xx, ad esempio da controlli della firma o da crash.
• Nessuna risposta entro 30 secondi.
• Reindirizzamenti. Emailit non segue 301 o 302, quindi un URL http:// che reindirizza a https://, o una barra finale mancante, falliscono ogni volta.
• Errori DNS, di certificato TLS o di connessione.

Le richieste non riuscite vengono ritentate dopo 5 minuti, 30 minuti, 2 ore, 5 ore e poi ogni 12 ore, fino a 11 tentativi. Emailit invia un’email al proprietario del workspace quando una richiesta non riesce per la terza volta. Se l’endpoint continua a non rispondere correttamente senza nessuna consegna riuscita per 3 giorni, il webhook viene disattivato e il proprietario riceve un’altra email.

Mentre un webhook è disattivato, i nuovi eventi non vengono messi in coda per lui.

Soluzione

1. Trova l’errore. Apri il webhook e seleziona la scheda Requests. Apri una richiesta non riuscita per vedere Failure reason, Status code e il corpo della risposta restituito dal tuo endpoint.

2. Correggi l’endpoint. Correzioni comuni:

   • Usa l’URL finale, con https:// e il percorso esatto, in modo che non ci siano reindirizzamenti.
   • Restituisci 200 rapidamente e svolgi il lavoro lento in un job in background, così resti sotto i 30 secondi.
   • Correggi la verifica della firma. Vedi Perché la firma del webhook non corrisponde?.
   • Lascia passare le richieste di Emailit nel firewall, nel WAF o nella protezione antibot.

3. Provalo. Scegli Send test, seleziona un tipo di evento e verifica che la finestra mostri uno stato 2xx.

4. Riattiva e invia di nuovo. Scegli Retry failed. Rimette in coda tutte le richieste non riuscite degli ultimi 7 giorni e riattiva il webhook. Puoi anche selezionare Enable webhook, oppure chiamare Ritenta le richieste non riuscite.

5. Recupera gli eventi del periodo di disattivazione. Gli eventi creati mentre il webhook era disattivato non sono stati messi in coda. Recuperali con Elenca gli eventi, filtrando per type e created_at.

Per rendere il gestore più robusto, rendilo idempotente con il campo event_id, perché un batch ritentato può arrivare due volte. Vedi Nuovi tentativi ed errori.

Serve ancora aiuto?

Contatta il supporto o chiedi su Discord indicando l’ID del webhook (wh_…) e il motivo dell’errore mostrato nella scheda Requests.