Automazioni webhook

Piano Basic e superiori

I webhook richiedono un piano a pagamento. Basic: 1 webhook, Pro: 3, Ultra: 10.

I webhook ti permettono di collegare TellDone a qualsiasi servizio esterno. Quando crei una nota vocale, TellDone la elabora e invia automaticamente i dati estratti - note, attività, eventi e report - a un URL che indichi tu. Ogni attività ed evento viene inviato come consegna separata, così il tuo strumento di automazione può gestirli singolarmente.

Scegliere cosa inviare

Ogni automazione ha i suoi toggle del payload. Scegli uno o qualsiasi combinazione:

• Note - la nota completa elaborata (titolo, trascrizione, riepilogo, tag, lingua)
• Audio - sul piano Ultra, allega un link di download valido 24 ore al file audio insieme al payload della nota
• Attività - una consegna per ogni attività estratta
• Eventi - una consegna per ogni evento del calendario estratto
• Report - una consegna per ogni report giornaliero, settimanale, mensile o annuale generato

Puoi cambiare i toggle in qualsiasi momento dalle impostazioni dell'automazione: i cambiamenti si applicano solo ai nuovi eventi.

Configurare un webhook

1. Vai in Impostazioni > Integrazioni > Automazioni webhook
2. Tocca Nuova automazione

3. Inserisci un nome (es. "Il mio webhook Zapier")
4. Incolla l'URL del webhook dal tuo servizio di automazione
5. Scegli quali dati inviare: note, attività, eventi, report (o qualsiasi combinazione)
6. Opzionalmente, aggiungi un header di autenticazione: un token inviato come header Authorization per endpoint sicuri
7. Tocca Salva
8. Copia il signing secret - viene mostrato per intero solo quando crei l'automazione per la prima volta o dopo averlo ruotato. Ti serve se vuoi verificare l'autenticità del webhook
9. Tocca "Test" per inviare un payload di esempio al tuo endpoint senza creare un evento reale

suggerimento

L'URL del webhook deve usare HTTPS. Indirizzi HTTP e IP di rete privata non sono accettati.

Cosa viene inviato

Ogni consegna è un oggetto JSON con tre campi: event (il tipo di evento), timestamp e data (il contenuto effettivo). Ecco come appare ciascun tipo di evento.

Note (note.created)

Contiene il titolo generato dall'AI, la trascrizione completa, il riepilogo, il tipo di nota, i tag, la priorità, la lingua e la data di creazione.

{
  "event": "note.created",
  "timestamp": "2026-02-27T14:38:00Z",
  "data": {
    "note_id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Meeting notes - Project Alpha",
    "transcript": "Full transcript text...",
    "summary": "Brief AI-generated summary...",
    "type": "meeting",
    "tags": ["work", "project-alpha"],
    "priority": "high",
    "language": "en",
    "created_at": "2026-02-27T10:00:00Z"
  }
}

Sul piano Ultra, le consegne delle note possono includere anche un link alla registrazione audio (audio_url, audio_format, duration_seconds). Il link scade dopo 24 ore. Attivalo con l'opzione "Nota + Audio" quando crei l'automazione.

Attività (task.created)

Una consegna per attività. Una singola nota con 3 attività invia 3 webhook separati.

{
  "event": "task.created",
  "timestamp": "2026-02-27T14:38:01Z",
  "data": {
    "note_id": "550e8400-...",
    "note_title": "Meeting notes - Project Alpha",
    "task_id": "660f9511-...",
    "title": "Send proposal to client",
    "description": "Include pricing for Q2",
    "priority": "high",
    "due_date": "2026-03-01",
    "reminder_at": "2026-02-28T09:00:00Z",
    "tags": ["work"],
    "status": "todo",
    "created_at": "2026-02-27T10:00:00Z"
  }
}

Eventi (calendar_event.created)

Una consegna per evento del calendario.

{
  "event": "calendar_event.created",
  "timestamp": "2026-02-27T14:38:02Z",
  "data": {
    "note_id": "550e8400-...",
    "note_title": "Meeting notes",
    "event_id": "770a0622-...",
    "title": "Team standup",
    "description": "Weekly sync",
    "start": "2026-03-03T10:00:00+03:00",
    "end": "2026-03-03T10:30:00+03:00",
    "location": "Zoom",
    "is_all_day": false,
    "attendees": ["alice@example.com"],
    "tags": ["work"],
    "created_at": "2026-02-27T10:00:00Z"
  }
}

Report (report.created)

Inviato quando viene generato un report giornaliero, settimanale, mensile o annuale.

{
  "event": "report.created",
  "timestamp": "2026-02-28T00:05:00Z",
  "data": {
    "report_id": "880b1733-...",
    "report_type": "daily",
    "period_start": "2026-02-27",
    "period_end": "2026-02-27",
    "content_md": "# Daily Report\n\n...",
    "content_json": {
      "productivity_score": 72,
      "day_type": "productive",
      "tasks_created": 5,
      "tasks_completed": 3
    },
    "created_at": "2026-02-28T00:05:00Z"
  }
}

Sicurezza

Ogni consegna è firmata con HMAC-SHA256 usando il signing secret della tua automazione. I seguenti header sono inclusi in ogni consegna:

• X-LP-Signature - la firma HMAC-SHA256 (sha256=...)
• X-LP-Timestamp - timestamp Unix usato per la firma
• X-LP-Event - il tipo di evento (note.created, task.created, calendar_event.created, report.created)
• X-LP-Delivery-Id - ID univoco della consegna (utile per la deduplicazione)
• User-Agent - sempre TellDone-Webhooks/1.0

Gli header della firma vengono inviati con ogni consegna, indipendentemente dalle altre impostazioni.

Di default, ogni consegna include il signing secret della tua automazione nell'header Authorization - così strumenti come n8n Header Auth funzionano subito incollando il secret come valore auth. Se imposti un header di autenticazione personalizzato nelle impostazioni, sostituisce quello predefinito. Puoi usare due formati: Header-Name: value (invia l'header con quel nome) o un valore semplice (lo invia come Authorization: <value>).

Ogni automazione ha il suo signing secret, così ruotarne uno non incide sugli altri tuoi webhook. Il secret viene mostrato per intero solo quando crei l'automazione per la prima volta o dopo averlo ruotato. In tutti gli altri momenti viene mostrata solo un'anteprima (whsec_...last4). Per sostituirlo con uno nuovo, tocca "Ruota il secret" nelle impostazioni dell'automazione: questo genera una nuova chiave HMAC senza cambiare l'URL o l'header di autenticazione. Il vecchio secret smette di funzionare immediatamente.

Sono accettati solo URL HTTPS. HTTP, indirizzi IP e indirizzi di rete privata vengono rifiutati.

Verifica delle firme dei webhook

Verifica HMAC

Ogni consegna include un header di firma nella forma X-LP-Signature: sha256=<hex>. L'esempio qui sotto mostra come verificarlo in Python.

Ogni webhook è firmato così puoi confermare che provenga davvero da TellDone. La firma è calcolata come:

HMAC-SHA256(signing_secret, timestamp + "." + raw_body)

Il risultato è codificato in esadecimale e prefissato con sha256= nell'header della firma.

Usa il body grezzo della richiesta

TellDone serializza il JSON con spazi dopo i separatori (es. {"event": "note.created"}). Se fai parsing e ri-serializzi il body, la firma non corrisponderà. Verifica sempre rispetto ai byte grezzi del body della richiesta.

Python

import hmac
import hashlib

def verify_signature(raw_body: bytes, signature: str, timestamp: str, secret: str) -> bool:
    payload = f"{timestamp}.".encode() + raw_body
    expected = "sha256=" + hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

# Flask example
@app.route("/webhook/telldone", methods=["POST"])
def telldone_webhook():
    raw_body = request.get_data()  # raw bytes, NOT request.json
    signature = request.headers.get("X-LP-Signature", "")
    timestamp = request.headers.get("X-LP-Timestamp", "")

    if not verify_signature(raw_body, signature, timestamp, SIGNING_SECRET):
        abort(403)

    data = request.json
    # process webhook...

Node.js

const crypto = require("crypto");

function verifySignature(rawBody, signature, timestamp, secret) {
  const payload = `${timestamp}.${rawBody}`;
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(payload).digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express example (use express.raw to get the raw body)
app.post("/webhook/telldone", express.raw({ type: "application/json" }), (req, res) => {
  const rawBody = req.body.toString();
  const signature = req.headers["x-lp-signature"] || "";
  const timestamp = req.headers["x-lp-timestamp"] || "";

  if (!verifySignature(rawBody, signature, timestamp, SIGNING_SECRET)) {
    return res.status(403).send("Invalid signature");
  }

  const data = JSON.parse(rawBody);
  // process webhook...
});

Protezione dai replay (opzionale)

Per prevenire attacchi di replay, controlla che il timestamp sia recente:

import time

def verify_timestamp(timestamp: str, tolerance_seconds: int = 300) -> bool:
    try:
        return abs(time.time() - int(timestamp)) < tolerance_seconds
    except (ValueError, TypeError):
        return False

Errori comuni

Errore	Soluzione
Usare un body parsato e ri-serializzato	Usa il body grezzo della richiesta
JSON.stringify() in JS (compatto, senza spazi)	Usa il body grezzo o adegua la spaziatura a Python
Dimenticare il prefisso del timestamp	Il formato del payload è timestamp + "." + body
Confrontare le stringhe direttamente	Usa hmac.compare_digest o timingSafeEqual

Politica di retry

Se il tuo endpoint fallisce, TellDone riprova ogni consegna con backoff esponenziale (qualche minuto, poi intervalli più lunghi):

Tentativo	Ritardo
1° retry	30 secondi
2° retry	2 minuti
3° retry	15 minuti
4° retry	1 ora
5° retry	4 ore

Dopo 5 tentativi falliti, la consegna viene marcata come morta. Puoi comunque riprovarla manualmente dal Log delle consegne.

Come TellDone gestisce le diverse risposte:

• 2xx - consegnato con successo
• 4xx (tranne 429) - marcato morto subito, nessun retry (il tuo endpoint ha rifiutato esplicitamente i dati)
• 429 (Too Many Requests) - riprova, rispettando l'header Retry-After
• 5xx o timeout - riprova con la pianificazione sopra

Quando le consegne falliscono ripetutamente

Non devi tenere d'occhio il Log delle consegne per sapere quando qualcosa è rotto. TellDone osserva i fallimenti consecutivi per te e ti contatta in due fasi.

Dopo 3 fallimenti: avviso in Posta in arrivo

Dopo 3 consegne fallite consecutive, TellDone crea un messaggio nella tua Posta in arrivo sotto la categoria "Errori dei webhook". Il messaggio nomina l'automazione interessata e ti porta direttamente a Impostazioni > Integrazioni > Automazioni > [l'automazione fallita] > Log delle consegne così puoi ispezionare la risposta e decidere cosa fare.

suggerimento

Gli avvisi in Posta in arrivo significano che scopri delle automazioni rotte dal badge dell'icona dell'app, invece di accorgertene settimane dopo per dati mancanti nel tuo strumento a valle.

Dopo 20 fallimenti: disattivazione automatica

Disattivazione automatica

Se 20 consegne consecutive della stessa automazione falliscono (contate dopo l'avviso in Posta in arrivo), TellDone disattiva automaticamente l'automazione per smettere di interrogare un endpoint rotto e per proteggere la tua quota mensile di consegne. Risolvi il problema sulla destinazione, poi riattiva l'automazione da Impostazioni > Integrazioni > Automazioni.

Il contatore dei fallimenti consecutivi si azzera al successivo invio andato a buon fine.

Gestire i webhook

• Pausa/riprendi - disattiva qualsiasi automazione senza eliminarla, riattivala in qualsiasi momento
• Log delle consegne - visualizza tutte le consegne con stato, codice HTTP e tempo di risposta. Filtra per Consegnate o Errori. Tocca una consegna fallita e scegli "Riprova" per rinviarla senza aspettare il prossimo retry pianificato
• Test - tocca "Test" per inviare un payload di esempio (con "test": true nel body) al tuo endpoint senza creare un evento reale. Gli invii di test non contano sulla tua quota mensile
• Ruota il secret - genera un nuovo signing secret HMAC senza cambiare l'URL o l'header di autenticazione
• Modifica - aggiorna URL, header di autenticazione o toggle del payload (note / audio / attività / eventi / report). Le modifiche hanno effetto immediato
• Elimina - rimuove definitivamente l'automazione e tutti i suoi log delle consegne

Limiti delle consegne

La consegna dei webhook ha due limiti: una quota mensile (limite rigido, varia in base al piano) e un limite anti-burst orario (limite morbido, identico su tutti i piani a pagamento).

Piano	Webhook	Consegne mensili	Burst orario
Free	0	0	-
Basic	1	300	100
Pro	3	3.000	100
Ultra	10	15.000	100

Il piano Ultra supporta anche i link audio nei payload delle note (scadenza 24 ore).

Come si comportano i limiti:

• Quota mensile superata: la consegna viene contrassegnata come fallita senza nuovo tentativo. Le nuove consegne riprendono il 1° del mese successivo, quando il contatore si azzera.
• Limite orario superato: la consegna viene rinviata e ritentata dopo circa 5 minuti, così un breve burst non perde dati. È una protezione anti-burst morbida, non un rifiuto definitivo.

Gli invii di test e i nuovi invii manuali dal registro delle consegne non vengono contati in nessuno dei due limiti.

Filtrare gli eventi di test

Quando tocchi "Test", il payload include "test": true al livello superiore. Nel tuo strumento di automazione puoi controllare questo campo e saltare l'elaborazione quando è presente.

Guide per piattaforma

Per istruzioni di setup passo passo con il tuo strumento di automazione:

• Zapier - collega TellDone a migliaia di app con gli Zap
• Make - costruisci scenari di automazione visivi (ex Integromat)
• n8n - usa i webhook TellDone in workflow self-hosted o cloud
• Endpoint personalizzati - qualsiasi servizio che accetta richieste HTTPS POST funziona con i webhook TellDone

Casi d'uso popolari

• Inviare attività a un Google Sheet via Zapier
• Creare messaggi Slack dalle note via Make
• Loggare eventi a un CRM personalizzato via n8n
• Fare backup di tutte le note nello storage cloud
• Inoltrare i report a una dashboard di team

Vedi anche

• Posta in arrivo e supporto - se un webhook fallisce ripetutamente, vedrai un messaggio nella Posta in arrivo
• Zapier - configurazione passo passo di Zapier
• Make - configurazione passo passo di Make
• n8n - configurazione passo passo di n8n
• Todoist - sincronizzazione bidirezionale dedicata delle attività (niente webhook)
• Notion - integrazione Notion dedicata
• Inoltro email - ricevi i dati delle note via email