Un URL di ricezione pubblico può ricevere richieste da chiunque. Un attaccante può inviare un evento contraffatto a quell'URL, quindi la richiesta richiede autenticazione prima di avviare qualsiasi elaborazione.
Bird utilizza lo schema di firma Standard Webhooks. Autentica l'identificatore dell'evento e l'orario del tentativo insieme al body, quindi modificare uno qualsiasi di essi invalida la firma.
Cosa firma Bird?
Bird firma l'identificatore dell'evento, il timestamp del tentativo di consegna e il body grezzo della richiesta, uniti con dei punti.
Mantieni il body della richiesta inalterato fino a quando non hai verificato la firma. Il parsing e la serializzazione di JSON possono alterare i byte che Bird ha firmato.
| Header | Cosa contiene |
|---|---|
webhook-id | L'identificatore dell'evento, riutilizzato nei tentativi e nei replay. |
webhook-timestamp | L'orario del tentativo come timestamp Unix in secondi. |
webhook-signature | Una o più firme, separate da spazi. Ciascuna inizia con v1,. |
Converti il timestamp da secondi prima di confrontarlo con un orologio che riporta millisecondi.
Rimuovi il prefisso whsec_ dal secret del tuo endpoint e decodifica in base64 la parte restante per ottenere i byte della chiave.
Unisci identificatore, timestamp e body inalterato con dei punti. Calcola HMAC-SHA256 su quella stringa usando la chiave decodificata. Confronta il risultato con ogni firma fornita usando un confronto a tempo costante, il cui tempo di esecuzione non rivela quali byte corrispondono.
Perché la mia firma non corrisponde mai?
Un secret errato o un body della richiesta modificato possono far fallire ogni controllo della firma.
I framework web spesso eseguono il parsing di JSON prima che il tuo handler venga eseguito. Serializzare nuovamente quell'oggetto può cambiare spazi, ordine delle chiavi o formattazione numerica. Il JSON risultante può avere lo stesso significato ma produrre una firma diversa.
Configura questa route per conservare il body grezzo. Verifica che il secret appartenga a questo endpoint, soprattutto dopo un deploy o una rotazione.
Cosa dovrebbe rifiutare il mio handler?
Rifiuta una richiesta quando nessuna firma corrisponde o quando il timestamp firmato cade fuori dalla finestra temporale consentita.
Prova ogni firma in webhook-signature. Durante la rotazione del secret, una consegna trasporta firme da più secret validi. Accettare qualsiasi firma corrispondente consente ai ricevitori che usano l'uno o l'altro secret di continuare a funzionare.
Usa una tolleranza di cinque minuti sul timestamp, in entrambe le direzioni rispetto al tuo orologio. Una richiesta catturata dieci minuti prima fallisce anche se la sua firma è invariata. Mantieni l'orologio del server accurato per non rifiutare consegne autentiche.
Controlla webhook-id rispetto agli eventi già memorizzati. Un duplicato riconosciuto deve ricevere una risposta di successo senza ripeterne l'elaborazione, poiché ritentare la stessa consegna non aggiunge un nuovo evento.
Cosa succede se rifiuto una consegna?
Bird ritenta una consegna che riceve una risposta di errore o nessuna risposta prima del suo timeout.
Una risposta 400, ad esempio, registra il rifiuto e lascia la consegna idonea per un nuovo tentativo. Tutte le risposte non-2xx seguono la policy di retry. Il codice ti aiuta a diagnosticare l'errore nei tuoi log.
La pianificazione copre circa 27,5 ore prima degli aggiustamenti, dandoti tempo per correggere un secret errato. Retry dei webhook falliti descrive la pianificazione e come riprodurre gli eventi persi successivamente.
Restituisci 2xx solo dopo aver verificato e memorizzato in modo sicuro l'evento, oppure riconosciuto un duplicato già memorizzato. Bird salta le consegne riuscite durante il replay, quindi confermare una richiesta non verificata impedisce il recupero tramite quel meccanismo.
Devo implementare la verifica da solo?
Non è necessario implementare la verifica da solo quando usi webhooks.unwrap in un Bird SDK. Passagli il body grezzo e gli header della richiesta.
L'helper verifica la firma e il timestamp prima di restituire l'evento decodificato. La tua applicazione deduplica comunque tramite webhook-id, perché è lei a possedere il registro del lavoro completato.
Una libreria di verifica Standard Webhooks compatibile può eseguire gli stessi controlli. La guida ai webhook include esempi e un'implementazione manuale.
In breve
Verifica i byte originali.
Il parsing e la serializzazione di JSON possono alterare i byte che Bird ha firmato. Conserva il body grezzo per la verifica.
Controlla anche il tempo, non solo la firma.
Una tolleranza di cinque minuti sul timestamp limita il riutilizzo di richieste catturate. Deduplica gli eventi memorizzati tramite webhook-id separatamente.
Prova ogni firma fornita.
La rotazione crea firme sovrapposte. Una corrispondenza con qualsiasi firma valida consente al deploy di proseguire.
Conferma solo eventi verificati e memorizzati.
Bird ritenta le risposte non-2xx e salta le consegne riuscite durante il replay. Restituisci successo per i duplicati già memorizzati senza ripeterne l'elaborazione.