Scegliere gli eventi webhook da sottoscrivere

dosya può notificare a una destinazione tre tipi di evento: file.uploaded, file.deleted e share.accessed. Sottoscrivi solo le modifiche che il ricevitore può autenticare ed elaborare. La scelta filtra le notifiche future per quella destinazione; non riproduce le attività precedenti al salvataggio.

Significato degli eventi

Evento	Quando viene generato	Campi in data
file.uploaded	Un nuovo file termina il caricamento o una nuova versione termina la sostituzione di un file esistente, inclusi i caricamenti tramite app web, CLI, WebDAV, SFTP o gateway S3.	file_id, name, size in byte, folder_id nullable, version numerico e is_new_version
file.deleted	Un file passa nel cestino o viene eliminato definitivamente. Eliminare una cartella genera un evento per ogni file discendente interessato.	file_id, name e permanent booleano
share.accessed	Una condivisione pubblica viene visualizzata, un file condiviso viene scaricato o viene scaricato l’archivio di una cartella condivisa.	share_id, token, access_type, accessed_at e file_id o folder_id, secondo il caso

Considera file.uploaded sia “nuovo file” sia “nuova versione”. Distingui i casi con data.is_new_version; non dedurli dal nome dell’evento. Per l’eliminazione, permanent: false indica il passaggio nel cestino, mentre permanent: true indica che il file è stato eliminato definitivamente e non può essere ripristinato. L’accesso alla condivisione usa valori access_type come view, download e download_all; una visualizzazione può identificare un file, una cartella o un gruppo.

Ogni payload contiene anche id, type, l’ora created in secondi Unix, workspace_id e data al livello principale. Le intestazioni della richiesta ripetono l’identità dell’evento come X-Dosya-Event-Id e il nome scelto come X-Dosya-Event-Type. Usa id al livello principale come chiave persistente per la deduplicazione.

Passaggi

1. Apri Integrazioni → Webhook con attivo lo spazio di lavoro della destinazione.
2. Trova l’URL della destinazione e scegli Modifica.
3. In Eventi, spunta File caricati, File eliminato o Accesso alla condivisione. Almeno uno deve rimanere selezionato; altrimenti il modulo mostra Select at least one event type.
4. Controlla URL di destinazione, Descrizione (facoltativa) e Attiva nella finestra, poi scegli Salva modifiche.
5. Verifica che la scheda della destinazione mostri gli indicatori con i nomi degli eventi previsti.

L’amministrazione dei webhook richiede l’appartenenza allo spazio di lavoro e il permesso manage_settings. Una credenziale REST limitata deve avere Accesso completo per amministrare le destinazioni. Se l’API riceve una stringa non supportata, risponde con unknown event type: VALUE; un elenco vuoto restituisce events must be a non-empty array.

L’equivalente REST è PATCH /api/webhooks/{endpoint_id}. Invia l’intero elenco sostitutivo perché events descrive la sottoscrizione salvata della destinazione, non un elemento da aggiungere all’elenco esistente:

curl --fail-with-body --silent --show-error --request PATCH \
  "https://api.dosya.dev/api/webhooks/$DOSYA_WEBHOOK_ID" \
  -H "Authorization: Bearer $DOSYA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{"events":["file.uploaded","file.deleted"]}'

Non usare share.created, folder.created o member.joined: non sono tipi di evento webhook accettati dall’API attuale.

Verifica la sottoscrizione con azioni reali

Invia un evento di prova invia sempre un payload sintetico file.uploaded con data.test: true, anche se la destinazione è sottoscritta solo a un altro evento. Usalo per verificare la raggiungibilità dell’URL e la gestione della firma, poi esegui un’azione reale innocua per ogni tipo scelto:

• Carica un piccolo file di prova eliminabile e controlla is_new_version: false.
• Carica una nuova versione dello stesso file e controlla is_new_version: true con un numero di versione superiore.
• Sposta il file di prova nel cestino e verifica permanent: false; eliminalo definitivamente solo se i dati sono sacrificabili.
• Apri una condivisione di prova, poi scaricala e verifica che il ricevitore distingua view da download.

Apri Invii sulla scheda della destinazione e confronta event_type, ora di creazione, stato e ID evento con il log del ricevitore. Un ricevitore funzionante deve autenticare il corpo originale, salvare l’ID evento in modo persistente e restituire 2xx solo dopo l’accettazione persistente. Ricevere due volte un evento non deve ripetere un effetto esterno.

Risultato previsto

La scheda della destinazione elenca solo i nomi degli eventi necessari. Ogni azione controllata nel prodotto crea un invio firmato corrispondente e il ricevitore registra l’evento una volta con i campi documentati. I tipi non scelti non creano invii per quella destinazione.

Guide correlate

• Creare una destinazione webhook
• Controllare i tentativi di invio webhook
• Verificare la firma webhook