Nuovi tentativi ed errori

Quando il tuo endpoint non accetta una richiesta webhook, Emailit conserva gli eventi e ritenta l’invio secondo un calendario che dura poco più di tre giorni. Questa pagina riporta il calendario, spiega le email che Emailit invia e quando disattiva un endpoint, e mostra come esaminare e reinviare le richieste non riuscite.

Cosa conta come errore

Una richiesta non riesce quando il tuo endpoint:

• Restituisce uno stato qualsiasi al di fuori di 200–299, compresi i reindirizzamenti (3xx).
• Non risponde entro 30 secondi.
• Non è raggiungibile: errori DNS, connessioni rifiutate, errori TLS o un URL che si risolve in un indirizzo IP privato.

Un errore riguarda l’intero batch: tutti gli eventi della richiesta vengono ritentati insieme.

Calendario dei nuovi tentativi

Dopo ogni tentativo non riuscito, Emailit attende prima di ritentare:

Se il tentativo 11 non riesce, la richiesta viene contrassegnata come Failed e non viene più ritentata automaticamente. Puoi comunque reinviarla per 7 giorni.

Ogni tentativo viene firmato di nuovo con un timestamp aggiornato. Gli eventi che arrivano mentre le richieste precedenti sono in attesa di un nuovo tentativo vengono inviati in batch separati, così un evento problematico non blocca quelli più recenti.

Email di notifica

Emailit invia un’email al proprietario del workspace in due momenti:

Disattivazione automatica

Se un webhook non ha avuto nessuna consegna riuscita per 3 giorni a partire dalla sua richiesta non riuscita più vecchia, Emailit lo disattiva al successivo tentativo non riuscito. In pratica succede intorno all’undicesimo tentativo della prima richiesta non riuscita, o prima se anche i nuovi eventi continuano a non riuscire.

Mentre un webhook è disattivato:

• I nuovi eventi non vengono messi in coda per quel webhook. Vengono comunque registrati nel flusso di eventi.
• Le richieste che erano in attesa di un nuovo tentativo restano in sospeso e riprendono quando lo riattivi.
• La pagina del webhook mostra lo stato Disabled.

Per riattivarlo, seleziona Enable webhook nel menu delle azioni del webhook, oppure chiama Aggiorna un webhook con {"enabled": true}. Anche Retry failed e il nuovo tentativo di una singola richiesta riattivano il webhook.

La scheda Requests

Apri un webhook in Email API›Webhooks per vedere la sua scheda Requests, a partire dalle richieste più recenti:

Filtra per Status code, Event o Created. Gli eventi di test inviati con Send test non compaiono qui.

Per una richiesta Failed, seleziona View per aprire Failure reason: il codice di stato restituito dal tuo endpoint (0 se non c’è stata una risposta HTTP), quando la richiesta è stata creata e quando non è riuscita, e i primi 2000 caratteri del corpo della risposta.

Reinvia le richieste non riuscite

Puoi reinviare le richieste contrassegnate come Failed il cui ultimo errore risale agli ultimi 7 giorni. Le richieste reinviate tornano a Pending e iniziano un nuovo ciclo di tentativi dal tentativo 1. La consegna non è immediata: il ciclo di consegna successivo le prende in carico entro pochi secondi.

Ritenta una richiesta

Nella scheda Requests, seleziona Retry su una riga non riuscita. Il pulsante compare solo sulle richieste non riuscite negli ultimi 7 giorni.

L’endpoint API è Ritenta una richiesta, POST /v2/webhooks/{id}/requests/{request_id}/retry, che restituisce {"retried": 1, "id": "whr_…"}. Accetta solo richieste contrassegnate come Failed e restituisce 400 per le altre. Gli ID delle richieste (whr_…) non sono elencati da nessun endpoint pubblico, quindi per automatizzare con l’API usa invece Retry failed.

Ritenta le richieste non riuscite

Apri il menu delle azioni del webhook e seleziona Retry failed. Ogni richiesta non riuscita negli ultimi 7 giorni viene rimessa in coda, e il pannello mostra «Queued 3 failed request(s) for retry» con il numero effettivo, oppure «No failed requests in the last 7 days».

Con l’API, chiama Ritenta le richieste non riuscite:

curl -X POST https://api.emailit.com/v2/webhooks/wh_2xGk8Hd3RvN6qT1mWsB9cL4pZ7e/retry-failed \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

{ "retried": 42 }

Riprendi dopo un’interruzione

1. Correggi l’endpoint. Usa View su una richiesta non riuscita per vedere cosa ha restituito il tuo endpoint.

2. Conferma che funziona. Usa Send test dal menu delle azioni, oppure Invia un evento di test con l’API, e controlla di ricevere un 2xx.

3. Riattiva il webhook se Emailit lo ha disattivato.

4. Reinvia le richieste non riuscite. Seleziona Retry failed per rimettere in coda ogni richiesta non riuscita negli ultimi 7 giorni. Le richieste ancora contrassegnate come Attempting vengono ritentate secondo il loro calendario.

5. Colma le lacune. Gli eventi che si sono verificati mentre il webhook era disattivato non sono mai stati messi in coda, e gli errori più vecchi di 7 giorni non si possono reinviare. Leggili con l’API degli eventi per il periodo interessato ed elabora quelli che ti mancano.

Poiché i nuovi tentativi reinviano interi batch, rendi idempotente il tuo handler: salva ogni event_id e salta quelli che hai già elaborato. Vedi Richieste webhook.

Conservazione

Le richieste webhook seguono il periodo di conservazione dei Logs, quindi nel tempo le righe più vecchie spariscono dalla scheda Requests.

Vedi anche