Automazioni webhook

Da Basic in su

Le automazioni richiedono Basic o superiore. Basic: 1 automazione, Pro: 3, Ultra: 10. Con Free, la riga mostra Aggiorna per sbloccare le Automazioni.

Un webhook è un indirizzo web che riceve dati in automatico. Con le Automazioni, TellDone invia a quell'indirizzo ogni nuova nota con le sue attività e i suoi eventi non appena la nota è pronta, e ogni nuovo report non appena il report è pronto, così strumenti come Zapier, Make o n8n possono agire su di essi. Ogni attività e ogni evento viene inviato come consegna a sé.

Scegliere cosa inviare

Ogni automazione ha le sue impostazioni sotto Cosa inviare. Scegline una o una qualsiasi combinazione:

• Nota - la nota elaborata completa (titolo, trascrizione, riepilogo, tipo, etichette, priorità, lingua e data di creazione)
• Nota + audio - con il piano Ultra, aggiunge a ogni consegna di una nota un link di download del file audio valido 24 ore. Lascia attivo Nota: senza di esso non viene inviata nessuna nota
• Attività - una consegna per ogni attività estratta
• Eventi - una consegna per ogni evento di calendario estratto
• Report - una consegna per ogni report giornaliero, settimanale, mensile o annuale generato (i tipi di report inclusi nel tuo piano). I segnaposto dei giorni tranquilli e i report brevi delle settimane tranquille non vengono inviati

Puoi cambiare queste scelte in qualsiasi momento dalle impostazioni dell'automazione: le modifiche valgono solo per le nuove consegne.

Scegliere quando inviare

Sotto le scelte sui dati, quattro interruttori separati decidono quali modifiche fanno partire una consegna: Creato, Aggiornato, Completato ed Eliminato. Un trigger funziona solo insieme all'interruttore dei dati corrispondente sopra di esso. Per esempio, Completato invia le attività completate solo se Attività è attivo.

Creato viene inviato per le note che TellDone crea da una registrazione o da una nota di testo, e per le attività e gli eventi che contengono. Le attività e gli eventi che aggiungi a mano o con un assistente AI, e i nuovi elementi di Aggiungi a voce, non vengono inviati come Creato. Aggiornato, Completato ed Eliminato vengono inviati quando cambi un elemento nell'app o con Aggiungi a voce. Le modifiche fatte da Smart Context, da un assistente AI o in Todoist, Notion o Microsoft To Do non fanno partire nessuna consegna.

Il campo event di ogni consegna indica cosa è successo, per esempio task.created, task.completed o calendar_event.updated.

Configurare un webhook

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

3. Inserisci un nome (per esempio, "Il mio webhook Zapier")
4. Incolla l'URL del webhook dal tuo servizio di automazione
5. Scegli quali dati inviare (Nota, Nota + audio con Ultra, Attività, Eventi, Report) e quali trigger usare (Creato, Aggiornato, Completato, Eliminato)
6. Se vuoi, aggiungi un auth header: un token inviato come header Authorization per gli endpoint protetti
7. Tocca Salva
8. Copia il secret di firma: viene mostrato per intero solo quando crei l'automazione per la prima volta o dopo averlo rigenerato. Ti serve per verificare che le consegne arrivino davvero da TellDone (vedi Verificare le firme dei webhook)
9. Tocca Invio di prova per inviare un payload di esempio al tuo endpoint senza cambiare nessuno dei tuoi dati. Vedrai Riuscito con il codice HTTP e il tempo di risposta, oppure Errore con il motivo. Gli invii di prova non compaiono nel registro delle consegne

Cosa viene inviato

Ogni consegna è un oggetto JSON con tre campi: event (il tipo di evento), timestamp e data (il contenuto vero e proprio). Gli invii di prova includono anche "test": true. Ecco come appare ogni tipo di evento.

Note (note.created)

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

{
  "event": "note.created",
  "timestamp": "2026-02-27T14:38:00.512345+00:00",
  "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:00.284117+00:00"
  }
}

Con il 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 nell'automazione.

Attività (task.created)

Una consegna per attività. Una nota con 3 attività invia 3 consegne separate.

{
  "event": "task.created",
  "timestamp": "2026-02-27T14:38:01.204718+00:00",
  "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:00+00:00",
    "tags": ["work"],
    "status": "todo",
    "cancel_reason": null,
    "cancelled_at": null,
    "created_at": "2026-02-27T10:00:00.284117+00:00"
  }
}

Eventi (calendar_event.created)

Una consegna per ogni evento di calendario.

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

start e end sono in UTC. start_local, end_local, start_date e end_date usano il tuo fuso orario (timezone). Per un evento di tutto il giorno, end_date è l'ultimo giorno dell'evento.

Report (report.created)

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

{
  "event": "report.created",
  "timestamp": "2026-02-28T00:05:00.731902+00:00",
  "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": "planning",
      "tasks_created": 5,
      "tasks_completed": 3
    },
    "created_at": "2026-02-28T00:05:00.418253+00:00"
  }
}

Sicurezza

Ogni consegna è firmata con HMAC-SHA256 usando il secret di firma della tua automazione. Con ogni consegna vengono inclusi questi header:

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

TellDone invia un header Authorization solo se aggiungi un auth header nell'automazione. Puoi usare due formati: Header-Name: value invia un header con nome, mentre un valore semplice invia Authorization: <value>. Il tuo secret di firma non viene mai inviato in un header.

Ogni automazione ha il proprio secret di firma, quindi rigenerarne uno non influisce sugli altri tuoi webhook. Il secret viene mostrato per intero solo quando crei l'automazione per la prima volta o dopo averlo rigenerato. In tutti gli altri momenti viene mostrata solo un'anteprima (whsec_...last4). Per sostituirlo con uno nuovo, tocca Rigenera secret nelle impostazioni dell'automazione: genera una nuova chiave HMAC senza cambiare l'URL né l'auth header. Il vecchio secret smette di funzionare subito.

Sono accettati solo URL HTTPS con un nome di dominio. HTTP, indirizzi IP (pubblici o privati), URL con nome utente o password e domini che puntano a indirizzi di reti private vengono rifiutati. TellDone controlla di nuovo l'indirizzo a ogni invio. Se questo controllo fallisce, per esempio perché in quel momento il dominio non si risolve, la consegna viene interrotta e non viene ritentata.

Verificare le firme dei webhook

Ogni webhook è firmato, così puoi confermare che arrivi davvero da TellDone. La firma viene calcolata così:

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

Il risultato è codificato in esadecimale e preceduto da sha256= nell'header della firma.

Usa il corpo grezzo della richiesta

TellDone serializza il JSON con spazi dopo i separatori (per esempio {"event": "note.created"}). Se analizzi e poi ri-serializzi il corpo, la firma non corrisponderà. Verifica sempre sui byte grezzi del corpo 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");
  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  // timingSafeEqual throws if the lengths differ, e.g. when the header is missing
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// 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 (facoltativa)

Per prevenire gli 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 il corpo analizzato e ri-serializzato	Usa il corpo grezzo della richiesta
JSON.stringify() in JS (compatto, senza spazi)	Usa il corpo grezzo della richiesta
Dimenticare il prefisso del timestamp	Il formato del payload è timestamp + "." + body
Confrontare direttamente le stringhe	Usa hmac.compare_digest o timingSafeEqual

Politica di nuovo tentativo

Se il tuo endpoint non risponde, TellDone ritenta ogni consegna secondo questo programma:

Tentativo	Attesa
1º nuovo tentativo	30 secondi
2º nuovo tentativo	2 minuti
3º nuovo tentativo	15 minuti
4º nuovo tentativo	1 ora
5º nuovo tentativo	4 ore

Se anche il 5º nuovo tentativo fallisce, la consegna viene segnata come non riuscita e non viene ritentata di nuovo. Nell'app compare con una croce rossa. Puoi comunque reinviarla tu dal registro completo delle consegne: apri Tutte le consegne (il link compare quando un'automazione ha più di 5 consegne) e tocca Riprova sulla consegna non riuscita. L'elenco breve Consegne recenti non offre il nuovo tentativo.

Come TellDone gestisce le diverse risposte:

• 2xx - consegnata con successo
• 4xx (tranne 429) - segnata subito come non riuscita e non ritentata (il tuo endpoint ha rifiutato esplicitamente i dati)
• 429 (Too Many Requests) - ritentata dopo il numero di secondi indicato in Retry-After (60 secondi se non c'è). Questi tentativi non sono limitati a 5, ma ognuno conta per i 20 errori che fanno disattivare l'automazione
• 5xx o timeout - ritenta secondo il programma qui sopra

Quando le consegne falliscono ripetutamente

Se le consegne continuano a fallire, TellDone ti avvisa e alla fine disattiva l'automazione.

Dopo 3 tentativi falliti: avviso nella casella In arrivo

Dopo 3 tentativi falliti di fila (contano anche i nuovi tentativi), TellDone invia un messaggio nella tua casella In arrivo intitolato La tua automazione "Nome" non funziona, con il nome della tua automazione tra virgolette. Puoi poi aprirla in Impostazioni > Integrazioni > Automazioni, controllarne le consegne e decidere cosa fare.

Dopo 20 tentativi falliti: disattivazione automatica

Disattivazione automatica

Se 20 tentativi di fila falliscono per la stessa automazione (contano anche i nuovi tentativi), TellDone disattiva l'automazione perché smetta di inviare a un indirizzo che non funziona. Risolvi il problema nel tuo strumento di automazione, poi riattiva l'interruttore Attiva in Impostazioni > Integrazioni > Automazioni. Riattivarla non azzera il conteggio degli errori, quindi finché una consegna non riesce, un solo tentativo fallito la disattiva di nuovo.

Ogni tentativo fallito conta, quindi una consegna che fallisce tutti e 5 i nuovi tentativi aggiunge 6 al conteggio. Un'automazione può quindi disattivarsi da sola dopo circa 4 consegne che falliscono. Il contatore torna a zero alla prima consegna riuscita.

Gestire i webhook

• Attiva - disattiva questo interruttore per fermare un'automazione senza eliminarla, e riattivalo quando vuoi. Finché è disattivata non viene inviato nulla: le note e i report di quel periodo non vengono inviati in seguito, e le consegne in attesa di un nuovo tentativo vengono scartate
• Consegne - Consegne recenti mostra le ultime 5 con stato, codice HTTP e tempo di risposta. Quando ce ne sono di più, Tutte le consegne apre il registro degli ultimi 30 giorni, dove puoi filtrare per Tutti, Consegnate o Errori e toccare Riprova su una consegna non riuscita per reinviarla senza aspettare il prossimo tentativo programmato
• Invio di prova - invia una nota di esempio (note.created, con "test": true nel corpo), qualunque tipo di dati tu abbia scelto, senza cambiare nessuno dei tuoi dati. Disponibile dopo aver salvato l'automazione. Gli invii di prova non contano per il tuo limite mensile
• Rigenera secret - genera un nuovo secret di firma HMAC senza cambiare l'URL né l'auth header
• Modifica - aggiorna l'URL, l'auth header, le scelte sui dati (Nota / Nota + audio / Attività / Eventi / Report) o i trigger (Creato / Aggiornato / Completato / Eliminato). Le modifiche hanno effetto subito
• Elimina automazione - rimuove definitivamente l'automazione e tutti i suoi registri di consegna

Ogni consegna mostra il suo stato con un'icona:

Icona	Significato
Spunta verde	Consegnata
Orologio giallo	In attesa o in invio
Triangolo rosso	Non riuscita, TellDone riproverà
Croce rossa	Non riuscita, nessun altro tentativo automatico

Nel registro completo puoi toccare Riprova sulle consegne con un triangolo rosso o una croce rossa.

Limiti di consegna

Ci sono due limiti: un limite mensile che dipende dal tuo piano e un limite orario di 100 consegne con ogni piano a pagamento, che protegge dai picchi improvvisi.

Piano	Automazioni	Consegne al mese	Limite orario
Free	0	0	-
Basic	1	300	100
Pro	3	3.000	100
Ultra	10	15.000	100

Come si comportano i limiti:

• Limite mensile raggiunto - la consegna aspetta. Compare come non riuscita ("Monthly webhook limit exceeded") e TellDone riprova ogni 5 minuti. Parte dopo l'azzeramento del limite alle 00:00 UTC del 1º del mese, a meno che in quel momento abbia più di 30 giorni. Le consegne inviate dopo l'azzeramento contano per il nuovo mese.
• Limite orario raggiunto - la consegna viene rinviata e ritentata dopo circa 5 minuti, così un breve picco non fa perdere dati.

Solo le consegne riuscite contano per il limite mensile. Il limite orario conta ogni tentativo, compresi i nuovi tentativi. Gli invii di prova non contano per nessuno dei due limiti.

Se cambi piano, le tue automazioni e le loro impostazioni vengono mantenute. Con Free smettono di inviare e non puoi aprirle finché non passi a un piano superiore. Con Basic, le automazioni che avevi già continuano a inviare entro 300 consegne al mese, ma non puoi aggiungerne né attivarne più di una.

Filtrare gli eventi di prova

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

Guide per piattaforma

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

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

Idee

• Invia le attività a un foglio Google tramite Zapier
• Crea messaggi Slack dalle note tramite Make
• Registra gli eventi in un CRM personalizzato tramite n8n
• Fai il backup di tutte le note in un archivio cloud
• Inoltra i report a una dashboard del team

Vedi anche

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