I tuoi receiver possono essere distribuiti in momenti diversi. Una sovrapposizione permette a un receiver che usa il vecchio secret e a uno che usa il nuovo di autenticare la stessa consegna.
Continua a verificare le consegne durante tutto il deployment, così una richiesta di un attaccante non può attivare elaborazioni.
Cosa succede quando ruoto?
Bird ti fornisce un nuovo secret di firma. Distribuiscilo entro 24 ore, mentre Bird firma ancora con il vecchio secret.
Chiama rotateWebhookSecret per il tuo endpoint. Salva il suo secret, una stringa non vuota che inizia con whsec_, perché viene restituito solo in quella risposta.
Bird firma ogni consegna con entrambi i secret durante la sovrapposizione. L'header webhook-signature contiene firme separate da spazi, ciascuna che inizia con v1,.
Un receiver può verificare una delle due firme usando il secret corrispondente. Completa il deployment entro 24 ore perché il vecchio secret smette di firmare dopo quella finestra.
Cosa deve fare il mio handler?
Il tuo handler deve accettare una consegna quando una qualsiasi firma fornita corrisponde a un secret di cui si fida.
Un receiver che verifica solo la prima firma può rifiutare consegne valide dopo aver cambiato secret.
La specifica Standard Webhooks definisce una lista di firme in modo che i receiver possano provarne ciascuna durante la rotazione. Testa il tuo verificatore con firme multiple prima di ruotare un endpoint in produzione.
Mantieni attivi i controlli di timestamp e duplicati durante tutto il cambiamento. Verifica della firma descrive questi controlli.
Qual è la sequenza sicura?
Salva e distribuisci il nuovo secret. Conferma la verifica prima che la sovrapposizione del vecchio secret termini.
- Ruota il secret dell'endpoint e salva immediatamente il valore restituito.
- Distribuisci il nuovo valore a ogni istanza receiver entro la sovrapposizione di 24 ore.
- Conferma che i receiver verificano le consegne usando il nuovo secret, tramite i log dei receiver e i tentativi di consegna di Bird.
- Lascia che il secret precedente scada automaticamente dopo la sovrapposizione.
Non esiste un passaggio di rimozione separato nell'operazione di rotazione. Se il vecchio secret è stato esposto, smetti di considerarlo attendibile nei tuoi receiver dopo che hanno ricevuto il nuovo. La sola rotazione lascia esposti durante la sovrapposizione i receiver che si fidano del vecchio secret.
Cosa succede se ruoto di nuovo subito?
Un'altra rotazione può riuscire finché l'endpoint non raggiunge cinque secret validi contemporaneamente.
Partendo da un secret, quattro rotazioni possono riempire quei cinque slot prima che i secret più vecchi scadano. La rotazione successiva fallisce con WebhookTooManySecrets. Un ciclo di rotazioni può quindi impedire l'emissione di un nuovo secret quando ne hai bisogno.
Attendi che un secret più vecchio scada prima di ruotare di nuovo. Rotazioni ripetute non eliminano la necessità di distribuire il nuovo secret ai tuoi receiver.
Cosa succede alle consegne fallite durante il cambiamento?
Bird ritenta le consegne fallite, quindi correggere la verifica può recuperarle durante la finestra di retry.
La pianificazione copre circa 27,5 ore prima degli aggiustamenti temporali. Una consegna fallita può anche essere recuperata tramite replay dopo il termine dei retry; retry dei webhook falliti spiega la finestra di replay.
Restituisci un errore per una richiesta che non riesci a verificare. Restituire 2xx segna la consegna come riuscita, escludendola dal replay degli eventi mancanti.
In breve
Distribuisci durante la sovrapposizione.
Bird firma con il vecchio e il nuovo secret per 24 ore, dando ai receiver il tempo di adottare il nuovo valore.
Accetta qualsiasi firma corrispondente.
Un receiver che verifica solo la prima firma può rifiutare una consegna valida durante la rotazione.
Salva il nuovo secret immediatamente.
La risposta di rotazione è l'unico punto in cui il nuovo secret viene restituito.
La rotazione ha un limite di cinque secret.
Partendo da un secret valido, quattro rotazioni riempiono gli slot disponibili prima che un secret più vecchio scada.