DeepScript

Integrazione

Integrazione n8n – automazione audio self-hosted

Il tuo n8n + i tuoi server DeepScript = piena sovranità dei dati. Nessuna automazione cloud, nessun rischio Schrems II.

n8n è l'alternativa self-hostable a Zapier e Make – gestisci tu stesso il motore di workflow, ad esempio sullo stesso server Hetzner del resto della tua infrastruttura. In combinazione con DeepScript (anch'esso ospitato in Germania), si crea una pipeline in cui dati audio, di workflow e metadati non toccano mai provider cloud statunitensi – ideale per ospedali, studi legali e pubblica amministrazione. Una node community DeepScript ufficiale è in preparazione; nel frattempo usa la node HTTP Request generica di n8n con l'header `X-API-KEY`. Di seguito trovi un export completo del workflow in JSON, che puoi importare nella tua istanza n8n (`Workflows → Import from File`). I webhook di ritorno verso n8n funzionano tramite la node Webhook, così anche le trascrizioni lunghe (> 30 min) girano senza problemi senza un loop di polling.

Documentazione n8n: node HTTP Request

Cosa puoi creare

  • Tutto self-hosted: n8n + container DeepScript + il tuo reverse proxy = piena sovranità dei dati su un'unica macchina.
  • Node HTTP Request con header `X-API-KEY` – nessun plugin aggiuntivo, funziona out of the box.
  • Node Webhook per gli eventi `transcription.completed`, un flusso asincrono pulito senza polling.
  • Diramazioni, loop, code node (JavaScript/Python) – logica complessa direttamente nel workflow.
  • Ideale per pubblica amministrazione, ospedali e studi legali: nulla finisce nel cloud statunitense, tutto resta sulla tua macchina.

Esempi di codice

JSON del workflow n8n – upload + callback webhookJSON
{
  "name": "DeepScript: Upload and Process",
  "nodes": [
    {
      "name": "Manual Trigger",
      "type": "n8n-nodes-base.manualTrigger",
      "typeVersion": 1,
      "position": [240, 300],
      "parameters": {}
    },
    {
      "name": "Read Audio File",
      "type": "n8n-nodes-base.readBinaryFile",
      "typeVersion": 1,
      "position": [440, 300],
      "parameters": { "filePath": "/data/audio/meeting.mp3" }
    },
    {
      "name": "Upload to DeepScript",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4,
      "position": [640, 300],
      "parameters": {
        "method": "POST",
        "url": "https://api.deepscript.com/v1/transcriptions",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            { "name": "X-API-KEY", "value": "={{ $env.DEEPSCRIPT_API_KEY }}" }
          ]
        },
        "sendBody": true,
        "contentType": "multipart-form-data",
        "bodyParameters": {
          "parameters": [
            { "name": "file", "value": "={{ $binary.data }}", "parameterType": "formBinaryData" },
            { "name": "model", "value": "premium" },
            { "name": "language", "value": "de" }
          ]
        }
      }
    },
    {
      "name": "Webhook (transcription.completed)",
      "type": "n8n-nodes-base.webhook",
      "typeVersion": 1,
      "position": [840, 300],
      "parameters": {
        "path": "deepscript-completed",
        "responseMode": "responseNode"
      }
    },
    {
      "name": "Get Transcript",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4,
      "position": [1040, 300],
      "parameters": {
        "method": "GET",
        "url": "=https://api.deepscript.com/v1/transcriptions/{{ $json.data.transcriptionId }}",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            { "name": "X-API-KEY", "value": "={{ $env.DEEPSCRIPT_API_KEY }}" }
          ]
        }
      }
    }
  ],
  "connections": {
    "Manual Trigger": { "main": [[{ "node": "Read Audio File", "type": "main", "index": 0 }]] },
    "Read Audio File": { "main": [[{ "node": "Upload to DeepScript", "type": "main", "index": 0 }]] },
    "Webhook (transcription.completed)": { "main": [[{ "node": "Get Transcript", "type": "main", "index": 0 }]] }
  }
}
n8n Code node – verifica la firma HMACJavaScript
// In an n8n Code node placed right after the Webhook node.
// Verifies the X-DeepScript-Signature header against the raw body.
const crypto = require("crypto");

const SIGNING_SECRET = $env.DEEPSCRIPT_WEBHOOK_SECRET; // "whsec_xxx"
const header = $input.first().json.headers["x-deepscript-signature"];
const rawBody = $input.first().json.body;

const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const { t: timestamp, v1: signature } = parts;

if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
  throw new Error("Webhook timestamp out of tolerance (>5min)");
}

const signedPayload = `${timestamp}.${JSON.stringify(rawBody)}`;
const expected = crypto
  .createHmac("sha256", SIGNING_SECRET)
  .update(signedPayload)
  .digest("hex");

const valid = crypto.timingSafeEqual(
  Buffer.from(signature, "hex"),
  Buffer.from(expected, "hex")
);
if (!valid) throw new Error("Invalid webhook signature");

return [{ json: { verified: true, event: rawBody } }];

Configurazione in pochi passaggi

  1. 1

    Installa n8n o avvia il container Docker

    Tramite Docker: `docker run -d --name n8n -p 5678:5678 -v ~/.n8n:/home/node/.n8n n8nio/n8n`. In produzione consigliamo di eseguire n8n dietro Caddy o Traefik con TLS Let's Encrypt sullo stesso server del resto della tua infrastruttura.

  2. 2

    Salva la chiave API come credential

    In n8n, in Credentials, crea un nuovo «Generic Credential Type» con nome header `X-API-KEY` e valore `ds_live_xxx`. In alternativa: monta la chiave API come variabile d'ambiente `DEEPSCRIPT_API_KEY` e referenziala nei node HTTP tramite `{{ $env.DEEPSCRIPT_API_KEY }}`.

  3. 3

    Importa il workflow

    Copia l'export JSON sopra in un file `.json`, poi `Workflows → Import from File`. n8n rileva automaticamente le node – devi solo associare il credential DeepScript ed eventualmente regolare i percorsi dei file.

  4. 4

    Registra il webhook in DeepScript

    La node Webhook di n8n ti fornisce una URL come `https://your-n8n.example.com/webhook/deepscript-completed`. Registra questa URL su `POST /v1/webhooks` con l'evento `transcription.completed`. Memorizza il secret restituito nella node Code di verifica HMAC.

Domande frequenti

Mi serve la community node o basta HTTP Request?

HTTP Request è sufficiente per ogni caso d'uso – l'API è abbastanza semplice. Una community node è in lavorazione, ma porterà soprattutto funzionalità di comodità (loop di auto-polling, output tipizzati). Nulla di funzionale che tu non possa già fare oggi.

Posso eseguire n8n sullo stesso server del mio reverse proxy?

Sì – consigliato. Setup Docker Compose con Caddy o Traefik davanti a n8n. Con diversi workflow al secondo ha senso l'architettura queue mode di n8n (worker + Redis). Per volumi bassi è sufficiente la modalità single-instance.

Quanto possono essere grandi i file audio nella node HTTP Request?

Il limite di body predefinito di n8n è di 16 MB. Per sfruttare il limite di upload di 500 MB di DeepScript, imposta `N8N_PAYLOAD_SIZE_MAX=512` (in MB) sulla tua istanza n8n. Alternativa per file molto grandi: carica prima su uno storage compatibile S3 e invia solo la URL all'API DeepScript.

Qualche dato lascia la mia infrastruttura?

Solo il file audio e i metadati vanno a DeepScript (Hetzner DE). Se esegui DeepScript anche sul tuo hardware (setup enterprise), pure questo resta in-house. I dati dei workflow n8n, i credential e i log restano comunque sul tuo server.

Posso versionare i workflow in Git?

Sì – dalla versione 1.0 n8n supporta l'integrazione Git nativa tramite Source Control (funzionalità enterprise). Community edition: esporta i workflow in JSON e committali manualmente. Quest'ultima soluzione è sufficiente per la maggior parte dei setup.

Pronto a portarlo in produzione?

Crea un account, genera una chiave API e parti. Tre trascrizioni gratuite per provare. Documentazione OpenAPI 3.1 completa su api.deepscript.com/docs.

Integrazione n8n – self-hosted & conforme al GDPR | DeepScript