Gestire le versioni dei payload webhook

L’attuale involucro webhook di dosya non ha un campo di versione dello schema. La sua struttura esterna stabile comprende id, type, created, workspace_id e data; data.version in un caricamento è la versione del file, non dello schema del payload.

Passaggi

1. Verifica la firma sul corpo originale della richiesta, interpreta il JSON e richiedi al livello principale la stringa id, il tipo supportato type, il numero created, la stringa workspace_id e l’oggetto data.
2. Accetta solo i tipi di evento attuali file.uploaded, file.deleted e share.accessed. Invia gli input malformati o non supportati a una quarantena persistente invece di indovinare lo schema. Allega l’ID evento solo se id al livello principale ha superato la convalida; altrimenti registra un ID di tracciamento generato dal ricevitore.
3. Per file.uploaded, convalida file_id, name, size in byte, folder_id nullable, version intero e is_new_version booleano. Usa quella versione solo per ordinare le revisioni del file indicato.
4. Per file.deleted, convalida file_id, name e permanent booleano. Uno spostamento nel cestino invia false, mentre un’eliminazione definitiva di file o cartella invia true per ogni file cancellato.
5. Per share.accessed, richiedi share_id, il dato sensibile token, accessed_at e un access_type pari a view, download o download_all. Un view di gruppo può avere sia file_id sia folder_id impostati su null; convalida gli identificativi consentiti da quel tipo di accesso anziché richiederne uno per tutti. Non scrivere il token nella diagnostica.
6. Ignora i campi aggiuntivi non necessari al ricevitore, poi prova con una proprietà extra e una proprietà obbligatoria mancante. Il primo esempio deve essere elaborato; l’input malformato deve essere posto visibilmente in quarantena senza effetti parziali.

Poiché oggi non esiste una versione dello schema per l’instradamento, il codice che richiede payload.version rifiuterà ogni evento dosya valido. Distingui i casi per type e mantieni isolata la convalida specifica per evento, così potrai aggiungere consapevolmente un contratto futuro.

Risultato previsto

I payload attuali superano la convalida specifica per tipo, le proprietà aggiuntive non interrompono l’elaborazione e data.version resta un numero di revisione del file. Gli eventi malformati vengono rifiutati visibilmente senza esporre il token di condivisione o applicare operazioni parziali.

Ogni payload segnala una versione sconosciuta. Rimuovi il requisito della versione dello schema al livello principale: l’implementazione attuale non emette quel campo.

Un nuovo campo causa un rifiuto. Sostituisci il confronto di uguaglianza rigorosa degli oggetti con la convalida dei campi obbligatori, mantenendo i controlli di tipo sui campi usati dal ricevitore.

Guide correlate

• Guida rapida REST API
• Controllare gli invii webhook