Risorse · 54
Webhook: gestione di ripetizioni, ritardi e ripristino
Trasforma una notifica ricevuta in un effetto aziendale univoco e tracciabile, recuperabile dopo un errore.
Aggiornato · 3 min
Obiettivi di questa guida
- Autenticare le notifiche
- Separare la ricezione dall'elaborazione
- Prevenire effetti duplicati
- Recuperare gli eventi bloccati
Verifica rapida
- Quali byte sono firmati?
- Quando la ricezione è duratura?
- Due worker possono agire insieme?
- Il fornitore garantisce l'ordine?
- Come viene recuperato un evento perso?
Metodo passo passo
- 1
Leggere il contratto del fornitore
Tipi di record, versione, contesto dell'account, firme, tempistiche e regole di retry. Stripe dichiara che l'ordine di consegna non è garantito e che possono verificarsi duplicati; non applicare un ritardo specifico di Stripe a ogni API.
Risultato: contratto del fornitore datato.
- 2
Convalida prima degli effetti
Verifica le firme con la libreria e il corpo grezzo richiesti dal fornitore. Limita le dimensioni e i tipi accettati. Testa le firme non valide e il contesto dell'account imprevisto in un ambiente autorizzato senza registrare i segreti.
Risultato: rifiuti senza effetti.
- 3
Persevera prima della conferma
Separa la ricezione permanente dall'elaborazione lenta. Se la coda non può accettare l'evento, non segnalarlo come conservato. Il successo indica la ricezione in base al contratto, non necessariamente il completamento dell'azione aziendale.
Risultato: stati di ricezione, elaborazione, completamento e blocco.
- 4
Applica l'idempotenza
Definisci le chiavi degli eventi e l'identità dell'effetto aziendale. Testa le ripetizioni simultanee anziché solo la consegna sequenziale. Un controllo preliminare senza vincoli atomici o blocchi può consentire a due worker di creare lo stesso effetto.
Risultato: prova dell'unicità dell'effetto.
- 5
Gestire ritardi e disordine
Non presumere che una vecchia notifica descriva lo stato attuale. Consultare la fonte quando il contratto lo consente e applicare transizioni aziendali validate. Conservare gli eventi che non possono ancora essere interpretati.
Risultato: transizioni e test in ordine inverso.
- 6
Riconciliazione e riproduzione
Preparare una coda di errori con proprietario, causa, tentativi e chiusura. Mantenere la protezione dai duplicati durante la riproduzione. Confrontare periodicamente il fornitore e l'applicazione: un ripristino riuscito non dimostra che non sia stato perso alcun evento.
Risultato: procedura di ripristino e report delle discrepanze.
Foglio di lavoro riutilizzabile
Completare con le proprie osservazioni autorizzate. Questi campi costituiscono un modello di lavoro, non risultati osservati.
| Campo | Informazioni da registrare |
|---|---|
| Evento | Provider, account, identificativo e versione |
| Ricevuta | Firma convalidata e timestamp permanente |
| Effetto | Chiave aziendale, stato e prova di unicità |
| Ripristino | Causa, tentativo, proprietario e chiusura |
Esempio pratico fittizio
Situazione illustrativa
Esempio fittizio: due operatori ricevono la stessa notifica di conferma durante il ripristino.
Decisione e prove attese
Un vincolo di effetto aziendale unico e uno stato transazionale consentono un unico adempimento mentre entrambe le consegne rimangono tracciabili.
Distinguere i meccanismi
| Meccanismo | Scopo | Verifica o limitazione |
|---|---|---|
| Firma | Convalidare l'origine ai sensi del contratto | Non rende gli effetti univoci |
| Deduplicazione | Riconoscimento delle notifiche ripetute | Verifica anche la concorrenza e gli effetti sul business |
| Riconciliazione | Individuazione di omissioni e differenze | Indicazione della fonte e del periodo |
Indicatori di gestione
| Indicatore | Cosa misura | Prima azione |
|---|---|---|
| Età della coda | Ritardo degli eventi non completati | Ispezione degli eventi più vecchi |
| Effetti duplicati | Azioni di business ripetute per errore | Correzione dell'atomicità |
| Lacune tra fonte e applicazione | Stati assenti o divergenti | Riconciliazione con la prova di chiusura |
Errori comuni
- Analisi sintattica prima della verifica del corpo firmato
- Conferma prima della ricezione permanente
- Presupposto di consegna ordinata
- Verifica dei duplicati solo in sequenza
Domande frequenti
Il successo HTTP significa che l'elaborazione è completa?
Dipende dal contratto. Con l'elaborazione asincrona, dovrebbe significare ricezione permanente mentre lo stato di business viene tracciato separatamente.
È possibile presumere una consegna "esattamente una sola volta"?
Progettare per gestire ripetizioni e guasti nell'ambito del contratto reale, con effetti unici e riconciliazione.
È necessario conservare l'intero corpo del contratto?
Solo quando necessario, con accesso e conservazione adeguati. Le tracce minime devono supportare la diagnosi e il ripristino senza mantenere segreti.
Riferimenti ufficiali
I riferimenti supportano il metodo. Adattare i controlli al proprio contesto; non costituiscono una certificazione. I titoli dei riferimenti originali e i documenti di origine potrebbero essere in un'altra lingua.
Riferimenti consultati il .
