Skip to main content
CasaBlogGuideCosa dovrebbe restituire un endpoint webhook di monitoraggio? Codici di stato, timeout e nuovi tentativi?

Cosa dovrebbe restituire un endpoint webhook di monitoraggio? Codici di stato, timeout e nuovi tentativi?

17TRACK

Un endpoint webhook di tracking dovrebbe restituire una risposta 2xx rapida e intenzionale dopo aver accettato l'evento per l'elaborazione. Nella maggior parte delle integrazioni, il modello più sicuro consiste nell'autenticare la richiesta, convalidare il payload, memorizzare o accodare l'evento e confermarlo con 200 OK o 202 Accepted. Usa risposte 4xx per le richieste che il mittente non dovrebbe ritentare e risposte 5xx quando un problema temporaneo lato server ha impedito l'accettazione. Il comportamento esatto relativo a timeout e tentativi dipende comunque dal contratto del provider del webhook, quindi l'implementazione dovrebbe essere progettata in base al comportamento documentato del mittente e non a supposizioni.

Quali codici di stato e timeout dovrebbe restituire un endpoint webhook di tracking

Per un webhook di tracking o di stato della spedizione, questa distinzione è importante perché gli eventi di consegna possono arrivare più di una volta, fuori ordine o essere riprodotti dopo un errore di rete. Il compito dell'endpoint non è necessariamente completare ogni operazione aziendale prima di rispondere. Il suo primo compito è prendere una decisione affidabile sull'accettazione dell'evento.

Il contratto della risposta in termini pratici

Una risposta webhook ha due destinatari: il sistema mittente e la tua applicazione. Il mittente ha bisogno di un risultato HTTP chiaro per decidere se contrassegnare la consegna come riuscita, ritentarla o interromperla. La tua applicazione ha bisogno di tempo sufficiente per verificare e registrare l'evento in modo durevole. Questi obiettivi sono più facili da raggiungere quando l'endpoint dispone di un piccolo percorso sincrono e di un percorso separato per l'elaborazione asincrona.

  1. Ricevi la richiesta HTTP tramite HTTPS.
  2. Controlla la firma, le credenziali di autenticazione, il timestamp o gli altri controlli di integrità della richiesta richiesti dal provider.
  3. Analizza e convalida il payload senza eseguire operazioni lente sui sistemi downstream.
  4. Scrivi l'evento, oppure un record di deduplicazione e un riferimento all'evento, in uno storage durevole o in una coda affidabile.
  5. Restituisci una risposta 2xx intenzionale.
  6. Elabora in modo asincrono l'aggiornamento del tracking, la notifica al cliente, la modifica dell'inventario o un'altra azione aziendale.

Una risposta non dovrebbe dichiarare l'accettazione se l'evento esiste solo nella memoria del processo. Se l'applicazione si arresta subito dopo aver restituito il successo, un evento mai persistito potrebbe andare perso mentre il mittente ritiene che la consegna sia riuscita. Il momento in cui restituisci 2xx dovrebbe quindi corrispondere alla tua effettiva garanzia di durabilità.

Quale codice di stato dovrebbe restituire un webhook?

RispostaSignificato per il mittenteUso tipico del webhook
200 OKLa richiesta è stata accettata e gestita correttamente.Un valore predefinito pratico dopo la convalida e l'accettazione durevole.
202 AcceptedLa richiesta è stata accettata per l'elaborazione, ma il lavoro potrebbe continuare.Utile quando l'evento è stato accodato in modo sicuro, ma l'elaborazione aziendale è asincrona.
204 No ContentLa richiesta è riuscita e non è necessario alcun corpo della risposta.Adatto quando il provider accetta una risposta di successo vuota.
400–499La richiesta non è valida, non è autorizzata o non è accettabile così com'è stata inviata.Payload malformato, autenticazione non riuscita, firma non valida o evento rifiutato definitivamente.
429 Too Many RequestsIl destinatario sta applicando un limite di frequenza.Usalo solo quando il comportamento di retry del mittente e la tua policy di limitazione sono compatibili.
500–599Il destinatario non ha potuto accettare la richiesta a causa di un problema lato server o temporaneo.Interruzione del database, errore della coda, errore di una dipendenza o errore imprevisto dell'applicazione.

200 OK è spesso la scelta meno sorprendente perché è ampiamente interpretato come ricezione riuscita. Anche 202 Accepted è semanticamente utile quando l'endpoint ha accettato l'evento per un'elaborazione successiva. Nessuno dei due codici è automaticamente corretto: la documentazione del mittente può definire quali risposte 2xx siano considerate riuscite e alcuni provider possono aspettarsi un corpo o un tipo di contenuto specifico.

Non restituire una risposta 2xx solo perché la richiesta HTTP ha raggiunto il tuo server. Se la verifica della firma fallisce o il payload non può essere interpretato in modo sicuro, una risposta 4xx è generalmente più veritiera. Al contrario, non restituire 4xx per un'interruzione temporanea del database se l'evento potrebbe riuscire in seguito. Una risposta 5xx offre a un mittente in grado di ritentare la possibilità di inviare nuovamente l'evento, anche se il provider potrebbe applicare una propria policy.

Come devono essere gestiti i timeout?

I valori di timeout dei webhook sono specifici del provider. Non esiste un timeout HTTP universale utilizzato da ogni piattaforma di tracking e un mittente potrebbe smettere di attendere prima che la tua applicazione termini un'operazione lenta. Considera il timeout documentato del mittente come un limite massimo, non come un obiettivo. Normalmente l'endpoint dovrebbe rispondere molto prima di tale limite.

L'errore di progettazione più comune consiste nell'eseguire tutto il lavoro downstream prima di confermare il webhook. Un gestore potrebbe chiamare in sequenza un database, un sistema di gestione degli ordini, un servizio di notifica e una pipeline di analisi. Una sola dipendenza lenta può causare un timeout visto dal mittente, anche se l'applicazione completa il lavoro in seguito. Il mittente potrebbe quindi ritentare, creando elaborazioni duplicate o aggiornamenti concorrenti.

Limita il percorso sincrono al lavoro necessario per prendere una decisione sicura sull'accettazione. Di solito ciò include l'autenticazione della richiesta, la convalida di base dello schema, la memorizzazione durevole dell'evento e la pubblicazione nella coda. Affida a un worker l'arricchimento costoso, le richieste ai corrieri, i messaggi ai clienti e le chiamate alle API di terze parti. Monitora separatamente il tempo impiegato per ricevere, convalidare, rendere persistente e confermare l'evento rispetto al tempo impiegato per elaborarlo.

Un timeout non equivale a un'operazione aziendale non riuscita. Dal punto di vista del mittente, un timeout di solito significa che non ha ricevuto una risposta di successo utilizzabile. Il tuo servizio potrebbe aver memorizzato correttamente l'evento poco prima della chiusura della connessione. Per questo l'idempotenza e la deduplicazione sono necessarie anche quando l'endpoint sembra affidabile.

Cosa causa i retry?

Un mittente webhook può ritentare dopo un errore di connessione, un timeout o una risposta che il suo contratto classifica come non riuscita. La pianificazione esatta, il numero massimo di tentativi, l'algoritmo di backoff e la finestra di consegna variano in base al provider. Non promettere un numero fisso di retry a meno che non sia indicato nella documentazione del provider.

Il destinatario dovrebbe presupporre che i retry possano verificarsi e progettare il sistema di conseguenza:

  • Usa un identificativo dell'evento quando disponibile. Memorizzalo con un vincolo di unicità o con una chiave di deduplicazione equivalente.
  • Rendi l'elaborazione idempotente. Applicare due volte lo stesso aggiornamento dello stato di consegna non dovrebbe inviare due messaggi al cliente, creare due rimborsi o far avanzare un ordine in modo errato.
  • Conserva il payload originale o un record di audit utile. Ciò supporta la riproduzione, l'analisi e la riconciliazione.
  • Separa l'accettazione dall'elaborazione. Un worker può ritentare gli errori interni senza costringere il mittente a ripetere l'intero scambio HTTP.
  • Registra i codici di risposta e la latenza. Un aumento delle risposte 5xx, dei timeout o degli ID evento duplicati può rivelare un'interruzione prima che gli utenti segnalino aggiornamenti di tracking mancanti.

Un evento duplicato dovrebbe generalmente ricevere una risposta positiva se l'evento originale era già stato accettato in modo durevole. Restituire un errore per ogni duplicato può attivare retry non necessari. L'endpoint può registrare che l'evento era già stato rilevato, ignorare l'azione aziendale ripetuta e restituire la stessa classe di successo utilizzata per un evento appena accettato.

Quando restituire 4xx, 429 o 5xx?

Restituisci 4xx quando è improbabile che ritentare la stessa richiesta risolva il problema. Gli esempi includono una firma non valida, l'assenza dell'autenticazione richiesta, una struttura del payload non supportata o una richiesta che viola una regola di convalida permanente. Prima di scegliere 4xx, verifica se il mittente considera tale stato un errore permanente. Alcune piattaforme hanno regole proprie per le consegne non riuscite.

Usa 429 con attenzione. HTTP definisce 429 per la limitazione della frequenza e l'header Retry-After può comunicare quando un retry potrebbe essere appropriato. Tuttavia, non tutti i mittenti webhook interpretano 429 allo stesso modo. Se la coda è piena o il servizio è sovraccarico, verifica che il provider ritenti in modo sicuro e che la sua pianificazione dei retry non aggravi il sovraccarico. Una coda di ingresso con limiti e un piano di backpressure sono generalmente migliori che lasciare che le richieste falliscano in modo imprevedibile.

Restituisci 5xx quando il destinatario non può accettare l'evento in modo sicuro a causa di un problema temporaneo. Ciò include un database non disponibile, una scrittura nella coda durevole non riuscita o un errore interno che ha impedito la convalida o la persistenza. Restituire 200 mentre si elimina silenziosamente l'evento rende più difficile il recupero perché il mittente non ha motivo di riprovare.

Evita di affidarti a reindirizzamenti come 301, 302 o 307 per la consegna dei webhook. La gestione dei reindirizzamenti varia tra i client e il reindirizzamento di una richiesta firmata può creare ambiguità sulla destinazione, sul metodo e sul corpo. Configura invece il provider con l'endpoint HTTPS finale.

Una policy di risposta affidabile per gli eventi di tracking

Per la maggior parte delle integrazioni con webhook di tracking, la seguente policy è un punto di partenza ragionevole:

  1. Restituisci 200 o 202 dopo che l'evento ha superato l'autenticazione ed è stato memorizzato in modo durevole o inserito in una coda affidabile.
  2. Restituisci una risposta 4xx per una firma non valida, un'autenticazione non valida o un payload definitivamente inutilizzabile, seguendo le regole documentate del provider.
  3. Restituisci 5xx quando un errore temporaneo impedisce l'accettazione durevole.
  4. Restituisci una risposta positiva per un duplicato riconosciuto in modo sicuro, impedendo al contempo effetti aziendali duplicati.
  5. Mantieni rapido il gestore e misura la latenza della conferma.
  6. Testa gli scenari di timeout, retry, duplicazione, fuori ordine, malformazione e indisponibilità del provider prima del lancio in produzione.

Se stai integrando una API di tracking, inizia dalla documentazione webhook del provider e conferma i codici di successo accettati, il metodo di firma delle richieste, il timeout, i trigger dei retry, lo schema del payload e l'identificativo dell'evento. Per le integrazioni 17TRACK, la documentazione ufficiale della Tracking API è il riferimento corretto per verificare il contratto specifico del provider, invece di dedurlo dalla pratica HTTP generale.

Checklist di implementazione

  • L'endpoint è raggiungibile tramite HTTPS e dispone di un URL di produzione stabile.
  • L'autenticazione e la verifica della firma avvengono prima dell'elaborazione aziendale.
  • La richiesta originale o una rappresentazione verificabile viene conservata quando necessario per i controlli della firma e la risoluzione dei problemi.
  • L'evento viene reso persistente prima dell'invio della risposta positiva.
  • Le consegne duplicate sono sicure e non ripetono azioni irreversibili.
  • I worker possono ritentare l'elaborazione interna indipendentemente dal ciclo di retry HTTP del mittente.
  • I log includono ID evento, ora di consegna, codice di risposta, stato di elaborazione e ID di correlazione senza esporre segreti.
  • Gli avvisi distinguono timeout dell'endpoint, errori di convalida 4xx, interruzioni 5xx, ritardi della coda e consegne duplicate.
  • Il comportamento documentato del provider è stato testato con eventi reali o sandbox.

FAQ

È meglio 200 OK o 202 Accepted per un webhook?

200 OK e 202 Accepted non sono universalmente migliori l'uno dell'altro. Usa 200 OK quando la richiesta è stata accettata e la tua integrazione considera la risposta un successo generale. Usa 202 Accepted quando l'evento è stato accettato per un'elaborazione asincrona. Conferma che il mittente consideri riuscita la risposta 2xx scelta.

Un endpoint webhook dovrebbe attendere fino al completamento dell'elaborazione dell'aggiornamento del tracking?

Generalmente no. Dovrebbe attendere solo fino a quando l'evento è stato autenticato, convalidato e accettato in modo durevole. Il lavoro di lunga durata dovrebbe normalmente avvenire dopo la conferma, così una dipendenza lenta non causa un timeout e un retry evitabili.

Cosa dovrebbe accadere quando lo stesso evento di tracking arriva due volte?

Riconoscilo usando l'ID evento del provider o una chiave equivalente progettata con attenzione, ignora gli effetti collaterali duplicati e restituisci una risposta positiva se l'evento era già stato accettato. In questo modo i retry sono sicuri senza nascondere nuovi errori di elaborazione.

Una firma non valida dovrebbe restituire 400 o 401?

La scelta dipende dal tuo modello di autenticazione e dalle aspettative documentate del provider. Entrambi possono comunicare un rifiuto, ma la coerenza è più importante della scelta universale di uno dei due. Non confermare un evento di cui non puoi verificare l'autenticità.

Una risposta 5xx causa sempre un retry?

No. Molti sistemi webhook ritentano in caso di timeout ed errori server, ma i trigger e le pianificazioni dei retry sono specifici del provider. Considera i retry come un comportamento di integrazione documentato e verificali in un ambiente di test.

Fonti