DocTransform

Webhook

Ricevi un messaggio firmato appena un’esecuzione termina, senza controllare di continuo per scaricare il file

Un webhook è un indirizzo tuo che DocTransform chiama ogni volta che una delle tue esecuzioni termina. Pensa a un campanello: invece di chiedere ancora e ancora se l’esecuzione è finita, aspetti, e DocTransform suona quando lo è. Quel suono è un breve messaggio chiamato evento. Ti dice quale esecuzione è terminata e ti dà un link al file.

Creare un webhook

Ti serve una sola cosa: un indirizzo che inizia con https:// e che sia raggiungibile da internet. Uno strumento come Zapier te ne dà uno, e anche il tuo server.

  1. Apri la scheda Webhook

    Vai sulla tua pagina Account e trova la scheda Webhook. Premi Aggiungi Webhook.

  2. Incolla il tuo indirizzo

    Incollalo in Indirizzo a cui inviare gli eventi. Un’esecuzione è terminata e Un’esecuzione è fallita sono già selezionati, come Per tutti i modelli. Cambiali solo se ti serve.

  3. Salva e invia una prova

    Premi Salva Webhook, poi Invia evento di prova. La risposta compare nel Registro delle consegne della stessa schermata, così sai che funziona prima di un’esecuzione vera.

  4. Copia il segreto di firma

    Solo se il tuo codice verificherà gli eventi: sotto Segreto di firma premi Mostra, poi Copia. Chi usa Zapier, Make o n8n può saltare questo passo.

Puoi aggiungere fino a 5 webhook, uguali su ogni piano. I webhook si gestiscono solo nella pagina Account, non tramite l’API. Le consegne non contano mai nella tua quota.

Nota Controllare GET /runs/{id} continua a funzionare e non sparirà. Scrivi codice? Leggi Verificare i webhook. UsiZapier, Make o n8n? Ti serve solo l’indirizzo che questi strumenti ti danno.

Cosa arriva

Ogni evento è un POST con un corpo JSON in tre parti: type, timestamp (quando l’esecuzione è terminata) e data. Ogni chiave è sempre presente e vale null quando non si applica, così uno strumento associa gli stessi campi ogni volta. Non contiene mai contenuto del file, colonne, nomi di file o nomi di modello: per i dettagli, chiedi GET /runs/{id}.

run.succeeded viene inviato quando il file è pronto:

{
  "type": "run.succeeded",
  "timestamp": "2026-09-27T10:15:00Z",
  "data": {
    "run_id": "run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58",
    "template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
    "status": "succeeded",
    "download_url": "https://doctransform.xyz/api/v1/runs/run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58/download?expires=1790763300&signature=0000000000000000000000000000000000000000000000000000000000000000",
    "expires_at": "2026-09-30T10:15:00Z",
    "error": null
  }
}

run.failed viene inviato quando un’esecuzione termina senza file. Non ha link, e error.code è uno dei codici di errore:

{
  "type": "run.failed",
  "timestamp": "2026-09-27T10:15:00Z",
  "data": {
    "run_id": "run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58",
    "template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
    "status": "failed",
    "download_url": null,
    "expires_at": null,
    "error": {
      "code": "PIPELINE_FAILED",
      "message": "The pipeline failed while running the Template."
    }
  }
}

webhook.test è ciò che invia Invia evento di prova. Il suo link non funziona, quindi ignoralo con if type == "webhook.test":

{
  "type": "webhook.test",
  "timestamp": "2026-09-27T10:15:00+00:00",
  "data": {
    "run_id": "run_test",
    "template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
    "status": "succeeded",
    "download_url": "https://doctransform.xyz/api/v1/runs/run_test/download?expires=1790590500&signature=0000000000000000000000000000000000000000000000000000000000000000",
    "expires_at": "2026-09-28T10:15:00+00:00",
    "error": null
  }
}

Controllare che un evento sia autentico

Chiunque trovi il tuo indirizzo potrebbe inviargli dati. Ogni evento porta una firma che solo DocTransform e tu potete produrre, così il tuo codice distingue un evento vero da uno falso. Verificare i webhook spiega come, con esempi da copiare.

Nuovi tentativi e disattivazione

Un evento conta come consegnato solo quando il tuo indirizzo risponde con uno stato 2xx entro 10 secondi. I reindirizzamenti non vengono seguiti. Tutto il resto viene riprovato, quindi un breve guasto da parte tua non fa perdere nulla. Dopo ogni tentativo fallito DocTransform aspetta di più:

Dopo il tentativo fallitoAttesa prima del successivo
11 min
25 min
330 min
42 h
56 h
612 h
724 h
818 h

Sono 9 tentativi in circa 2,6 giorni (62 h 36 min, più o meno il 10 %). Che un evento già gestito si ripeta è normale: vedi Fermare ripetizioni e duplicati.

Quando le consegne falliscono

Il webhook resta attivo e mostra che sta fallendo. Apri il suo Registro delle consegne per vedere ogni tentativo e il motivo. Ricevi un’e-mail dopo 24 ore di errori. Quando il tuo indirizzo risponde di nuovo, il tentativo successivo consegna l’evento.

Il registro delle consegne assegna a ogni tentativo fallito uno di questi motivi:

MotivoIn parole sempliciCosa fare
WEBHOOK_UNREACHABLENon siamo riusciti a raggiungere il tuo indirizzo: non esiste, è offline o ci ha rifiutato.Controlla che l’indirizzo non abbia errori e che il tuo ricevitore sia in funzione.
WEBHOOK_TIMEOUTIl tuo indirizzo ha impiegato più di 10 secondi a rispondere.Rispondi prima e fai il lavoro lento dopo.
WEBHOOK_REJECTEDIl tuo indirizzo ha risposto, ma con un errore invece di uno stato 2xx.Guarda il registro del tuo ricevitore per capire perché ha detto no.
WEBHOOK_REDIRECTEDIl tuo indirizzo ci ha mandato a un altro indirizzo, e questo non lo seguiamo mai.Incolla invece l’indirizzo finale.
WEBHOOK_URL_BLOCKEDL’indirizzo punta a una rete privata, quindi abbiamo smesso di inviargli.Usa un indirizzo https pubblico. Per provare sul tuo computer, vedi Provare i webhook in locale.
WEBHOOK_SECRET_UNREADABLENon siamo riusciti a leggere il segreto di firma del webhook, quindi non è stato inviato nulla.Apri il webhook e premi Cambia segreto.
WEBHOOK_DISABLEDIl webhook era spento, quindi l’evento non è stato inviato.Premi Attiva.

Quando un webhook si disattiva

Dopo 10 tentativi falliti di fila, distribuiti su più di 5 giorni, il webhook passa a Disattivato e ricevi una seconda e-mail. Non viene più inviato nulla. Ripara il tuo indirizzo, poi premi Attiva: ti propone di rinviare le consegne fermate alla disattivazione, degli ultimi 3 giorni. Un’esecuzione terminata mentre il webhook era disattivato non viene inviata: prendi il suo file con GET /runs/{id}/output, o dal suo link di download finché dura. Puoi anche premere Reinvia su una singola consegna.

Quando il tuo indirizzo risponde «scomparso»

Se il tuo indirizzo risponde 410 Gone, il webhook si disattiva subito, perché quella risposta significa che non tornerà. Succede spesso quando uno Zap o uno scenario viene eliminato o lasciato spento. Rimetti in funzione il ricevitore, poi premi Attiva.

Scaricare il file

download_url scarica il file senza chiave API fino a expires_at. Sono 3 giorni dopo la fine dell’esecuzione quando un webhook la riceve, altrimenti 30 minuti, che è anche la durata di GET /runs/{id}/output. Vale null su run.failed e su una consegna inviata dopo la scadenza del file, come un Reinvia tardivo. Un link scaduto risponde DOWNLOAD_LINK_EXPIRED: esegui di nuovo il modello.

Attenzione Chiunque abbia il link può scaricare il file fino alla scadenza. Non incollarlo in nessun posto condiviso.

Provare i webhook in locale

DocTransform invia solo a indirizzi https pubblici, quindi localhost viene rifiutato. Un tunnel dà al tuo server locale un indirizzo pubblico. Questo non richiede un account:

cloudflared tunnel --url http://localhost:8000

Incolla in un webhook l’indirizzo che stampa, più il tuo percorso, poi premi Invia evento di prova. ngrok fa lo stesso lavoro. Elimina il webhook a lavoro finito, perché l’indirizzo del tunnel cambia ogni volta.

Vedere cosa è successo

Attività API nella tua pagina Account elenca ogni richiesta fatta dalle tue chiavi API negli ultimi 90 giorni, rifiuti compresi. Il Registro delle consegne di ogni webhook mostra ogni tentativo con la sua risposta e un pulsante Reinvia. Sono collegati dall’id dell’esecuzione: premi Vedi questa esecuzione per passare dall’uno all’altro.