Risolvere gli errori di invio webhook dosya

Usa la tabella Invii della destinazione e il log del ricevitore per lo stesso invio. La tabella indica evento, ora di creazione, stato, risposta, tentativi e prossimo tentativo; il ricevitore dovrebbe registrare gli ID non segreti di evento e invio. Non diagnosticare mai un errore di firma disattivando la verifica su una destinazione in produzione.

Passaggi

1. Apri Integrazioni → Webhook nello spazio di lavoro della destinazione.
2. Verifica che la scheda sia Attiva e includa l’evento previsto: file.uploaded, file.deleted o share.accessed.
3. Espandi Invii, apri la riga non riuscita e annota tipo di evento, ID invio ed evento, stato della risposta, tentativi, prossimo tentativo, errore ed estratto della risposta privo di dati sensibili.
4. Confronta l’ora del tentativo con i log del ricevitore e del nodo periferico o proxy. L’assenza di una richiesta in ingresso indica problemi di convalida URL/DNS/SSRF, connessione o proxy a monte; una richiesta arrivata ma rifiutata indica problemi di verifica o elaborazione del ricevitore.

L’amministrazione dei webhook richiede l’appartenenza allo spazio di lavoro e manage_settings. I ruoli predefiniti di proprietario e amministratore sono idonei. Un controllo Webhook mancante o un 403 You don’t have permission to manage webhooks richiedono una correzione del ruolo nello spazio; ruotare una chiave non amplia quel permesso del membro.

Collega l’errore al punto di ricezione

Sintomo	Soluzione
La creazione o modifica dell’URL restituisce Endpoint URL not allowed: …	Usa un ricevitore HTTPS pubblico. Localhost, reti private e destinazioni DNS o indirizzi non consentiti sono rifiutati alla registrazione e all’invio.
Il ricevitore non riceve POST	Verifica URL salvato, DNS pubblico e TLS, route del proxy, firewall e stato attivo della destinazione. Cerca un errore di convalida URL registrato nell’invio.
Il ricevitore restituisce 3xx	Configura l’URL HTTPS finale e stabile. dosya segue al massimo un reindirizzamento consentito; il secondo è registrato come errore.
L’invio supera il tempo limite	Conferma dopo autenticazione e accodamento persistente. Il ricevitore ha 10 secondi; esegui il lavoro lungo in modo asincrono.
La risposta è 4xx/5xx	Leggi i log del ricevitore per X-Dosya-Delivery-Id; correggi quella route e restituisci un 2xx solo dopo l’accettazione. Ogni risposta non 2xx è un tentativo non riuscito.
La firma non corrisponde	Verifica i byte intatti con il segreto whsec_… attuale della destinazione. Non analizzare o riformattare il JSON prima di calcolare HMAC.
La destinazione indica Disattivata automaticamente dopo errori ripetuti	Correggi e prova il ricevitore, poi scegli Riattiva. La riattivazione azzera il contatore di errori consecutivi, ma non ripara il lavoro precedente non riuscito.
Evento elaborato due volte	Deduplica tramite id dell’evento nell’involucro. I tentativi mantengono l’identità dell’evento; un reinvio manuale crea una nuova riga per lo stesso evento e payload.

dosya firma timestamp + "." + raw_body con HMAC-SHA256. L’intestazione è X-Dosya-Signature: t=TIMESTAMP,v1=LOWERCASE_HEX_HMAC. Confronta il digest a tempo costante e rifiuta timestamp distanti oltre 300 secondi dall’orologio del ricevitore. Registra anche X-Dosya-Event-Id, X-Dosya-Event-Type e X-Dosya-Delivery-Id; nessuna di queste intestazioni sostituisce la verifica della firma.

Se hai usato Sostituisci la chiave segreta di firma, il vecchio segreto ha smesso subito di funzionare. Aggiorna il ricevitore con il nuovo valore mostrato; non c’è periodo di sovrapposizione. Se perdi il valore mostrato, devi ruotarlo di nuovo. Non inserire firme e segreti nei log delle richieste.

Capire i tempi dei tentativi

Un invio ha sei tentativi totali: il primo è immediato, mentre i successivi sono previsti dopo 30 secondi, 2 minuti, 10 minuti, 1 ora e 6 ore in caso di errore. Pianificazione e rete possono aggiungere ritardo. Dopo il sesto errore l’invio resta non riuscito.

Quindici tentativi consecutivi non riusciti tra gli eventi disattivano automaticamente la destinazione. Qualsiasi tentativo riuscito azzera la sequenza. Riattivala solo dopo che un test controllato può riuscire, altrimenti ricominceranno gli errori.

Il corpo della risposta del ricevitore conservato in dosya è limitato a 500 caratteri. Restituisci una breve conferma neutra; non copiare credenziali, stack trace o contenuti privati nella risposta.

Invia un test controllato

Scegli Invia un evento di prova. Crea un evento sintetico file.uploaded con test: true, ID file test_file, nome test.txt e dimensione 12. Viene inviato anche se la destinazione è sottoscritta solo a un altro evento: il ricevitore dovrebbe riconoscere il contrassegno di test invece di trattarlo come contenuto di produzione.

La notifica Evento di prova inviato conferma solo che il test è in coda. Aggiorna Invii e attendi Completato, poi verifica che il ricevitore abbia salvato esattamente un evento autenticato. Le route di test e reinvio manuale consentono ciascuna 20 chiamate per utente ogni 300 secondi; una risposta 429 fornisce un Retry-After da rispettare.

Dopo il test sintetico, genera un evento innocuo effettivamente sottoscritto dalla destinazione. Verifica spazio di lavoro e metadati del payload, poi controlla che l’operazione a valle sia avvenuta una sola volta.

Invia di nuovo in sicurezza

Usa Invia di nuovo solo dopo aver verificato se la richiesta originale ha già cambiato lo stato a valle. Un timeout o una risposta persa possono lasciare riuscita l’operazione del ricevitore mentre dosya registra un errore. Cerca prima per ID evento, rendi idempotente il gestore e accoda un solo reinvio. Il messaggio Nuovo invio in coda — È stato programmato un nuovo tentativo di invio. non è il risultato finale: controlla la nuova riga.

Eliminare la destinazione rimuove definitivamente la cronologia degli invii e non può richiamare i payload già ricevuti. Conserva le prove non segrete prima di eliminarla. Anche la rotazione è immediata e irreversibile per il vecchio segreto.

Risultato previsto

Un nuovo invio di prova raggiunge la destinazione HTTPS prevista, supera una volta la verifica della firma sul corpo originale, restituisce una risposta riuscita entro il limite e non crea effetti duplicati.

Richiedi assistenza con prove correlate

Fornisci ID destinazione, ID evento e invio, tipo di evento, ora del tentativo UTC o locale, stato della risposta, numero di tentativi, estratto o errore privo di dati sensibili, framework del ricevitore e indicazione se la richiesta ha raggiunto il nodo periferico e l’applicazione. Non includere chiave segreta di firma, firma completa, intestazioni di autorizzazione, campi privati del payload o credenziali.

Guide correlate

• Creare un webhook
• Verificare le firme
• Controllare gli invii