Creare una destinazione webhook

Configura un webhook dello spazio di archiviazione cloud per ricevere notifiche JSON firmate sul tuo ricevitore HTTPS pubblico. dosya supporta file.uploaded, file.deleted e share.accessed. La creazione attiva subito la destinazione: distribuisci il ricevitore e prepara la conservazione privata del segreto prima di affidarti agli eventi di produzione.

Requisiti di accesso e del ricevitore

Scegli lo spazio di lavoro la cui attività deve raggiungere il server. Amministrare i webhook richiede appartenenza allo spazio e manage_settings: i ruoli predefiniti di proprietario e amministratore sono idonei, come un ruolo personalizzato con quel permesso. Una credenziale REST richiede anche Accesso completo, accesso al protocollo REST API e un vincolo di spazio compatibile con la destinazione. Una chiave di sola lettura o solo caricamento non può amministrare webhook.

L’URL del ricevitore deve usare HTTPS e risolversi in indirizzi pubblicamente raggiungibili. Localhost, destinazioni di rete privata e indirizzi non consentiti vengono rifiutati, anche se il DNS cambia dopo la creazione. Puoi usare un tunnel HTTPS pubblico di sviluppo se la destinazione supera la convalida; http://localhost non può essere registrato.

Il limite è 16 per spazio di lavoro, incluse le destinazioni inattive. Gli utenti del piano gratuito possono crearne 3 in totale tra i propri spazi di lavoro, conteggiate per creatore. Il limite dello spazio viene controllato prima di quello del piano gratuito. Elimina una destinazione inutilizzata solo dopo aver deciso se ti serve la cronologia degli invii.

Passaggi: crea la destinazione nell’app

1. Apri Integrazioni → Webhook con attivo lo spazio di lavoro previsto.
2. Scegli Nuova destinazione. In Nuova destinazione webhook, inserisci URL di destinazione.
3. In Eventi, scegli almeno uno tra File caricati, File eliminato e Accesso alla condivisione. Aggiungi Descrizione (facoltativa) se aiuta a identificare il ricevitore in seguito.
4. Scegli Crea una destinazione. Il modulo rifiuta un indirizzo non HTTPS con URL must be a valid https:// address. e una selezione vuota di eventi con Select at least one event type.
5. In Chiave segreta di firma, scegli Copia e salva il valore whsec_ nella configurazione segreta del ricevitore prima di uscire dalla finestra. Non verrà mostrato di nuovo.
6. La scheda dovrebbe mostrare Attiva e i nomi degli eventi sottoscritti. Scegli Invia un evento di prova, poi controlla Invii e i log del ricevitore.

Il pulsante di prova invia un evento sintetico file.uploaded con data.test: true, file_id: "test_file", name: "test.txt" e size: 12. Non crea un file reale. Il test viene inviato anche se la destinazione è sottoscritta solo a un altro evento: gestiscilo consapevolmente nel ricevitore. La notifica Evento di prova inviato conferma l’avvio; un invio riuscito e il record verificato del ricevitore confermano la ricezione.

Registra e prova tramite REST

Imposta DOSYA_API_KEY privatamente su una chiave autorizzata con accesso completo. Sostituisci gli esempi di spazio di lavoro e ricevitore con i tuoi valori:

set -e
umask 077
curl --fail-with-body --silent --show-error \
  'https://api.dosya.dev/api/webhooks' \
  -H "Authorization: Bearer $DOSYA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "workspace_id": "REPLACE_WITH_WORKSPACE_ID",
    "url": "https://receiver.example.com/dosya",
    "events": ["file.uploaded"],
    "description": "File processing receiver"
  }' -o webhook-created.json

receiver.example.com è un segnaposto non funzionante. La risposta 201 contiene ok: true e webhook con id, workspace_id, url, events, description, active: 1, source, secret e created_at. Copia webhook.secret nella configurazione privata del ricevitore, mai nel campo della chiave API. Una chiave segreta di firma webhook verifica gli eventi in uscita; non è un token di autenticazione REST.

Leggi webhook.id e invia il test dopo aver salvato il segreto:

DOSYA_WEBHOOK_ID=$(python3 -c 'import json; print(json.load(open("webhook-created.json"))["webhook"]["id"])')
curl --fail-with-body --silent --show-error --request POST \
  "https://api.dosya.dev/api/webhooks/$DOSYA_WEBHOOK_ID/test" \
  -H "Authorization: Bearer $DOSYA_API_KEY"
curl --fail-with-body --silent --show-error \
  "https://api.dosya.dev/api/webhooks/$DOSYA_WEBHOOK_ID/deliveries?page=1&per_page=10" \
  -H "Authorization: Bearer $DOSYA_API_KEY"

La risposta al test restituisce delivery_id; l’invio può essere ancora in corso quando arriva. L’elenco ne mostra stato, tentativi, codice di risposta ed eventuale errore registrato. Rimuovi webhook-created.json dopo aver salvato il segreto mostrato una volta. GET /api/webhooks?workspace_id=… elenca le destinazioni senza rivelarne i segreti.

Verifica ogni richiesta ricevuta

Il ricevitore riceve una POST HTTP con Content-Type: application/json, User-Agent: dosya-webhooks/1 e queste intestazioni:

• X-Dosya-Signature: t=TIMESTAMP,v1=LOWERCASE_HEX_HMAC
• X-Dosya-Event-Id: ID evento stabile
• X-Dosya-Event-Type: nome dell’evento
• X-Dosya-Delivery-Id: ID del record di invio

L’involucro JSON contiene id, type, created in secondi Unix, workspace_id e data. Un evento di caricamento fornisce file_id, name, size in byte, folder_id, version e is_new_version. Notifica il ricevitore; non include i byte del file né concede diritti di download.

Verifica HMAC-SHA256 usando la chiave segreta di firma su timestamp + "." + raw_body. Conserva i byte originali prima di analizzare il JSON; serializzarlo di nuovo può cambiare la firma. Confronta a tempo costante e rifiuta timestamp distanti oltre 300 secondi dal tuo orologio. Questa funzione Node.js usa solo il modulo crittografico integrato:

import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody must be a Buffer of the untouched HTTP request body.
export function verified(rawBody, signature, secret, now = Math.floor(Date.now() / 1000)) {
  const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(signature ?? '');
  if (!match || Math.abs(now - Number(match[1])) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(match[1] + '.').update(rawBody).digest();
  const received = Buffer.from(match[2], 'hex');
  return received.length === expected.length && timingSafeEqual(expected, received);
}

Analizza e accoda l’evento solo dopo la verifica riuscita. Salva un record di deduplicazione indicizzato da id dell’involucro prima di applicare effetti: i tentativi automatici conservano l’identità di evento e invio, mentre il reinvio manuale usa un nuovo ID invio per lo stesso evento e payload. Restituire 2xx prima dell’accettazione persistente rischia di confermare lavoro poi perso.

Tempi di invio e recupero

Ogni risposta 2xx indica un invio riuscito. Il ricevitore ha un limite di 10 secondi; accetta rapidamente e sposta l’elaborazione lunga in una coda persistente. Risposte non 2xx, timeout ed errori di convalida URL contano come tentativi non riusciti. Si può seguire un reindirizzamento consentito; un secondo è un errore. Un URL diretto e stabile è più facile da diagnosticare di una catena di reindirizzamenti.

Ci sono 6 tentativi in totale, non sei nuovi tentativi dopo il primo. Il primo è immediato; dopo errori successivi, le attese sono 30 secondi, 2 minuti, 10 minuti, 1 ora e 6 ore, misurate dal tentativo non riuscito precedente. Pianificazione e rete possono aggiungere ritardo; non sono scadenze di consegna garantite.

Una destinazione si disattiva automaticamente dopo 15 tentativi consecutivi non riusciti tra gli eventi. Un tentativo riuscito azzera la sequenza. Correggi il ricevitore, controlla Invii, poi usa Riattiva sulla scheda disattivata; la riattivazione azzera il contatore. Non riattivare un ricevitore ancora difettoso.

Per un invio conservato usa Invia di nuovo nel log espanso o POST /api/webhooks/{id}/deliveries/{delivery_id}/redeliver. Viene creato un altro record mantenendo ID evento e payload originali. Mantieni la deduplicazione affinché un nuovo tentativo non duplichi attività, fatture o azioni esterne. Le route di test e reinvio consentono ciascuna 20 chiamate per utente ogni 300 secondi; rispetta Retry-After di una risposta 429.

Errori di configurazione e modifiche irreversibili

Errore	Soluzione
400, Endpoint URL not allowed: …	Correggi HTTPS, DNS o il problema di convalida dell’indirizzo indicato. L’URL viene controllato alla registrazione e all’invio.
400, events must be a non-empty array	Invia almeno una stringa di evento supportata.
400, unknown event type: …	Usa esattamente file.uploaded, file.deleted o share.accessed.
403, API key scope 'full' required	Usa una credenziale autorizzata con accesso completo; cambiare ruolo non amplia da solo una chiave limitata.
403, You don't have permission to manage webhooks	Richiedi manage_settings all’amministratore dello spazio di lavoro.
400, Webhook endpoint limit reached (16 per workspace). Delete an unused endpoint first.	Controlla le destinazioni dello spazio, comprese quelle disattivate.
403, The free plan allows 3 webhook endpoints in total. Delete one or upgrade for more.	Controlla le destinazioni create da te in tutti gli spazi di lavoro.
404, Webhook not found o Delivery not found	Verifica gli ID e l’associazione alla destinazione prima di riprovare.

Sostituisci la chiave segreta di firma genera una nuova chiave segreta di firma e fa smettere subito di funzionare quella precedente, senza periodo di tolleranza. Prepara il ricevitore ad accettare subito la sostituzione, salva il nuovo valore mostrato e rimuovi quello vecchio. L’equivalente REST è POST /api/webhooks/{id}/roll-secret, che restituisce secret una volta e consente 10 rotazioni per utente all’ora. Se perdi il valore mostrato devi ruotare di nuovo.

Modifica può cambiare URL, eventi, descrizione e stato attivo. Elimina chiede conferma e rimuove definitivamente la destinazione e la sua cronologia degli invii; l’azione non può essere annullata. L’eliminazione ferma gli invii futuri a quella destinazione ma non può richiamare eventi o dati già ricevuti da un altro server.

Un estratto della risposta del ricevitore può essere conservato nel log fino a 500 caratteri. Restituisci una breve conferma neutra senza credenziali o dati riservati. Registra ID evento, ID invio ed errori privi di dati sensibili invece di segreti, firme o payload sensibili completi. Dopo il test sintetico invia un evento reale innocuo sottoscritto e verifica che sia accettato una volta prima di abilitare azioni di produzione a valle.

Risultato previsto

La destinazione è attiva nello spazio di lavoro scelto, il ricevitore verifica la firma e salva un solo record evento e Invii mostra il successo del test sintetico e di un evento innocuo sottoscritto. Il segreto salvato è conservato privatamente dal ricevitore; gli elenchi delle destinazioni non lo rivelano.

Guide correlate

• Configurare l’autenticazione REST
• Creare o revocare una chiave API di integrazione