Come vengono riprovati i webhook falliti e gli eventi arrivano in ordine?

Il tuo ricevitore può memorizzare un evento anche quando il mittente non riceve la conferma. Un nuovo tentativo può quindi ripetere un'operazione che la tua applicazione ha già accettato.

I tentativi ritardano alcuni eventi. Eventi più recenti possono arrivare prima che quei tentativi terminino. Memorizza gli identificatori degli eventi e i timestamp di occorrenza in modo che quelle consegne non possano sovrascrivere operazioni più recenti.

Cosa si considera una consegna fallita?

Bird considera una consegna fallita quando riceve una risposta di non-successo o la richiesta scade.

Restituisci HTTP 2xx dopo aver memorizzato l'evento per interrompere i tentativi per quella consegna. Un redirect, un errore client o un errore server resta idoneo per un nuovo tentativo.

Ad esempio, 400 registra una richiesta rifiutata ma non comunica a Bird di scartarla. Usa una risposta di errore quando la verifica della firma o la memorizzazione persistente fallisce, in modo che la consegna possa essere recuperata.

Memorizza l'evento prima di confermarlo. Restituire un successo per primo può causare la perdita dell'evento se l'operazione di memorizzazione successiva fallisce.

Mantieni le elaborazioni lente in un worker in background in modo che il tuo ricevitore possa rispondere rapidamente. Il compito del ricevitore è verificare e conservare l'evento prima che quell'elaborazione inizi.

Qual è la pianificazione dei tentativi?

Bird usa sette intervalli di attesa dopo il tentativo iniziale, per un totale di otto tentativi.

La pianificazione ti concede circa 27,5 ore per riparare un ricevitore prima che i tentativi automatici terminino.

Bird regola casualmente ogni attesa fino al 20 percento in più o in meno per distribuire i tentativi dopo un'interruzione. Un'attesa di cinque minuti varia quindi da quattro a sei minuti prima di altre regolazioni.

Una risposta di throttling o un timeout possono modificare l'attesa successiva. Bird considera anche Retry-After, un header di risposta che richiede un'attesa prima di un altro tentativo. Tratta la pianificazione come una finestra di recupero anziché come una scadenza esatta.

Ogni tentativo conserva il webhook-id dell'evento, così il tuo ricevitore può riconoscere i duplicati.

Cosa succede dopo l'ultimo tentativo?

I tentativi automatici si interrompono per quella consegna. Puoi richiedere il replay delle consegne fallite.

Richiedi la riconsegna con createWebhookReplay oppure dalla pagina dashboard dell'endpoint. Il replay legge il log dei tentativi di consegna e seleziona gli eventi che hanno fallito. Un evento Bird mai tentato, ad esempio uno arrivato mentre l'endpoint era in pausa, non ha un tentativo da selezionare, quindi il replay non può recuperarlo.

La risposta è 202, il che significa che il replay è accodato per l'esecuzione in background. Non include un conteggio né un identificatore di attività. Usa listWebhookAttempts per esaminare i tentativi successivi.

Ogni riconsegna usa un solo tentativo anziché la pianificazione descritta sopra. Bird registra il tentativo e chiude l'operazione indipendentemente dal fatto che il ricevitore l'abbia accettata. Riprodurre verso un ricevitore ancora guasto costa quindi una richiesta per evento anziché otto. Ripara il ricevitore, poi avvia di nuovo il replay. Questi fallimenti non influenzano lo stato di salute dell'endpoint. Una riconsegna accettata elimina il degrado.

Il replay salta le consegne già confermate con successo. Una riconsegna mantiene il proprio webhook-id originale, quindi la tua gestione dei duplicati continua a funzionare.

Imposta since e until come stringhe date-time per delimitare la finestra di recupero. Entrambi i limiti sono inclusivi. Entrambi vengono confrontati con l'ora del tentativo di consegna, non con l'ora in cui l'evento si è verificato. Omettendo since la finestra inizia 24 ore prima della richiesta, quindi un'interruzione più vecchia richiede un orario di inizio esplicito. Omettendo until la finestra termina all'ora della richiesta.

I tentativi vengono conservati per tre giorni, che è il limite temporale raggiungibile dal replay. Un since anteriore amplia la finestra senza recuperare nulla di più vecchio. Un singolo replay copre al massimo i 10.000 eventi più vecchi nella finestra, quindi un'interruzione prolungata richiede più finestre più strette.

Un'organizzazione può richiedere 20 replay per giorno UTC. Un'ulteriore richiesta riceve 429 con WebhookReplayQuotaExceeded, quindi combina il recupero in un'unica finestra invece di richiedere il replay per singolo evento.

Cosa succede se il mio endpoint continua a fallire?

Bird segna un endpoint in errore come degradato. Mette in pausa la consegna dopo circa cinque giorni di fallimenti ininterrotti.

Puoi leggere il suo status come active, degraded o paused. Un endpoint degradato continua a ricevere consegne e tentativi. Una consegna riuscita rimuove il degrado e azzera il contatore di fallimenti consecutivi.

Un endpoint in pausa smette di ricevere eventi e non riprende automaticamente. Riabilitalo con updateWebhook, impostando status su active. Poi esegui il replay della finestra, che recupera le consegne fallite prima della pausa. Riabilita prima: un replay richiesto mentre l'endpoint è ancora in pausa restituisce 202 e non riconsegna nulla. I valori di stato scrivibili sono active e paused.

Cambiare l'url di ricezione o completare una consegna di test riuscita rimuove anch'essa il degrado. L'URL sostitutivo deve essere raggiungibile pubblicamente HTTPS, quindi gli indirizzi privati non possono ripristinare la raggiungibilità. Gli URL più lunghi di 2048 caratteri non superano la validazione, quindi accorcia un URL generato prima di inviarlo.

Modificare la descrizione dell'endpoint o le sottoscrizioni agli eventi non dimostra che possa ricevere richieste. Queste modifiche lasciano il degrado in essere, così come una consegna di test fallita.

Bird invia un'email ai proprietari dell'organizzazione quando un endpoint diventa degradato. Non invia ulteriori email di degrado finché l'endpoint non si riprende. I fallimenti ripetuti quindi non producono un'email per ogni tentativo. Un fallimento dopo il ripristino avvia un nuovo periodo di degrado.

Esiste una dead-letter queue?

Bird non fornisce una coda separata di eventi falliti da leggere. Ispeziona i tentativi di consegna e richiedi il replay.

Ripara il ricevitore, riabilitalo se necessario ed esegui il replay della finestra interessata. Non c'è una coda separata da svuotare in seguito.

Gli eventi arrivano in ordine?

Gli eventi possono arrivare in un ordine diverso da quello in cui si sono verificati.

Un evento email.delivered può arrivare prima dell'evento email.accepted dello stesso messaggio. Confronta i tempi degli eventi in timestamp prima di applicare una modifica che sovrascriverebbe uno stato più recente.

Traccia separatamente ogni parte di un addebito SMS. Ad esempio, il costo di consegna e una tariffa dell'operatore sono componenti di costo distinte.

L'oggetto cost è null finché una componente non è stata tariffata. I valori delle componenti sono stringhe decimali o null. Il campo amount è una stringa decimale che somma le componenti presenti in quel payload.

Unisci ogni componente usando il timestamp dell'evento più recente. Sostituire l'intero oggetto può cancellare una componente fornita da un altro evento o ripristinare un addebito più vecchio.

Una componente null significa che non è stata tariffata in quel payload. Non indica un addebito pari a zero. Eventi SMS descrive quell'unione nel contesto e webhooks tratta la semantica di consegna.