Controllare e reinviare gli invii webhook

Il registro degli invii mostra i tentativi di dosya, quando è previsto il prossimo e cosa ha restituito il ricevitore. Usalo per distinguere un problema di generazione dell’evento da un errore di rete, firma o applicazione. Correggi il ricevitore prima di reinviare manualmente un evento.

Passaggi

Apri Integrazioni → Webhook, attiva lo spazio di lavoro previsto, trova la destinazione e scegli Invii. Invii recenti mostra dieci righe per pagina con queste colonne:

• Evento è il event_type sottoscritto, ad esempio file.uploaded.
• Creato indica quando è stato aggiunto il record dell’invio.
• Stato è In attesa, Completato o Errore.
• Risposta mostra lo stato HTTP, Error per un errore di trasporto registrato o - se non è ancora stato salvato un risultato.
• Tentativi conta le richieste completate, inclusa la prima.
• Prossimo tentativo è compilato solo mentre un invio non riuscito resta in attesa.

Passa il puntatore sulla cella Risposta per leggere l’errore registrato o l’estratto della risposta. dosya conserva al massimo i primi 500 caratteri: restituisci un corpo breve e neutro come ok; non ripetere token, dati personali, stack trace o payload della richiesta nella conferma.

Ogni richiesta in uscita contiene sia X-Dosya-Event-Id sia X-Dosya-Delivery-Id. I tentativi automatici di un invio conservato usano gli stessi identificativi. Invia di nuovo manuale crea un nuovo ID di invio, mantenendo l’ID evento e il payload JSON originali. Deduplica le operazioni per ID evento per mantenere sicuri entrambi i percorsi.

Capire i tentativi automatici

Qualsiasi stato HTTP da 200 a 299 è un successo. Una risposta non 2xx, un errore di rete, un URL della destinazione rifiutato o un ricevitore che non termina entro 10 secondi conta come tentativo non riuscito. dosya può seguire un reindirizzamento HTTPS consentito; un altro resta un errore non 2xx.

Sono previsti sei tentativi in totale. Dopo il primo tentativo immediato non riuscito, i successivi sono programmati dopo 30 secondi, 2 minuti, 10 minuti, 1 ora e 6 ore. I tempi di coda e rete possono allungare l’attesa osservata. Dopo il sesto errore, l’invio diventa Errore e non ha un prossimo tentativo.

Una destinazione raggiunge Disattivata dopo 15 tentativi di invio consecutivi non riusciti tra i suoi eventi. Un tentativo riuscito azzera quel conteggio. Quando la scheda indica Disattivata automaticamente dopo errori ripetuti, ripara prima il ricevitore e poi scegli Riattiva; questo azzera il contatore ma non invia retroattivamente gli eventi di prodotto persi.

Individua la causa di un tentativo non riuscito

1. Copia ID evento, ID invio, tipo di evento, risposta HTTP e ora registrata nel rapporto sull’incidente. Escludi firma e chiave segreta di firma.
2. Confronta l’ID invio con il log di accesso del ricevitore. L’assenza di una richiesta indica normalmente problemi DNS, TLS, di convalida dell’indirizzo pubblico, firewall o timeout.
3. Per una risposta 4xx, controlla l’analisi della firma e la route o il middleware di autenticazione del ricevitore. Per una risposta 5xx, correggi l’errore dell’applicazione prima di riprovare.
4. Verifica che il gestore legga il corpo intatto e convalidi X-Dosya-Signature prima di analizzare il JSON.
5. Riproduci il payload acquisito solo in un ambiente di test controllato, usando una firma volutamente non valida come test negativo. Non aggirare mai la verifica in produzione per rendere verde la riga.
6. Fai salvare al ricevitore il record di deduplicazione e l’attività in coda prima di restituire 2xx.

Se Invii non si apre, la gestione dei webhook richiede l’appartenenza allo spazio di lavoro e il permesso manage_settings. L’API REST richiede inoltre una credenziale con accesso completo; altrimenti restituisce API key scope 'full' required.

Invia di nuovo dopo la correzione

Scegli Invia di nuovo sulla riga interessata. La notifica Nuovo invio in coda indica che è stato creato un nuovo record di invio; non prova ancora che il ricevitore lo abbia accettato. Torna alla pagina 1, aggiorna Invii recenti e cerca la nuova riga. Un successo dovrebbe mostrare una risposta 2xx e un tentativo.

La sequenza REST è:

curl --fail-with-body --silent --show-error \
  "https://api.dosya.dev/api/webhooks/$DOSYA_WEBHOOK_ID/deliveries?page=1&per_page=25" \
  -H "Authorization: Bearer $DOSYA_API_KEY"

curl --fail-with-body --silent --show-error --request POST \
  "https://api.dosya.dev/api/webhooks/$DOSYA_WEBHOOK_ID/deliveries/$DOSYA_DELIVERY_ID/redeliver" \
  -H "Authorization: Bearer $DOSYA_API_KEY"

L’endpoint dell’elenco accetta page e limita per_page a 10–100, con valore predefinito 25. Una destinazione mancante restituisce Webhook not found; un invio che non le appartiene restituisce Delivery not found. Il reinvio manuale consente 20 chiamate per utente ogni 300 secondi e può restituire 429 con Retry-After se il limite viene superato.

Risultato previsto

Il nuovo invio raggiunge Completato, il log del ricevitore corrisponde ai suoi ID di invio ed evento e lo stato a valle cambia una volta. Conserva la riga originale non riuscita come prova dell’incidente; eliminare il webhook rimuove definitivamente la destinazione e tutta la cronologia degli invii.

Guide correlate

• Scegliere i tipi di evento sottoscritti
• Verificare le firme prima dell’elaborazione
• Risolvere errori di invio webhook