API Google Tasks, Webhooks e Zapier: soluzioni per utenti avanzati

Vuoi che venga creato un task in Google Tasks ogni volta che viene inviato un modulo. Oppure ricevere un messaggio su Slack quando un collega completa un’attività dalla lista condivisa. O ancora uno script notturno che archivi i task scaduti in un foglio di calcolo.

Google offre una Tasks API, e funziona. Ma non supporta webhook, quindi per sapere “quando un task è completato” devi controllare periodicamente ogni lista. Non gestisce etichette, assegnatari o board perché Google Tasks non li ha. E ogni script richiede un progetto Google Cloud, una schermata di consenso OAuth e una routine di aggiornamento token.

TasksBoard ora espone una REST API pubblica sui tuoi dati Google Tasks, con chiavi API personali, webhook firmati con HMAC e un’app per Zapier. Questa guida spiega cosa offre, come ottenere una chiave, gli endpoint più utili, il funzionamento di webhook e polling, e a chi è rivolto. L’API è inclusa nel piano Team.

Cosa aggiunge l’API di TasksBoard a Google Tasks

L’API legge e scrive le stesse liste e task di Google Tasks che vedi in Gmail e nell’app Google Tasks. Ogni ID lista e task è quello originale di Google Tasks, quindi tutto ciò che costruisci rimane compatibile con Google Tasks stesso e con altri strumenti che usano l’API di Google.

In più, espone ciò che TasksBoard aggiunge:

• Etichette e assegnatari come campi dedicati. Google Tasks memorizza solo titolo, note e data di scadenza; TasksBoard conserva etichette e assegnatario nelle note (etichette nella prima riga, poi 👤 Assegnato a <email>). L’API li legge e scrive come labels e assignee, così il testo libero in notes è ciò che le persone vedono sulla board.
• Board: quali liste mostra ogni board di TasksBoard.
• Liste condivise: un flag shared su ogni lista, ed eventi quando un collaboratore modifica un task condiviso.
• Webhook per task.created, task.updated, task.completed e task.deleted.

URL base: https://api.tasksboard.com/v1. Le risposte sono JSON sotto una chiave data; gli errori arrivano come { "error": { "code", "message", "details" } }, dove code è stabile e details elenca i campi non validi in caso di 422.

Crea una chiave API

Le chiavi sono personali. Una chiave agisce come l’utente che l’ha creata: tutto ciò che quella persona può fare in Google Tasks, la chiave può farlo.

1. In TasksBoard, clicca sul tuo avatar e apri Team, poi la scheda API (o vai direttamente a /team?tab=api).
2. Clicca per creare una chiave. Scegli se può scrivere; una chiave senza permessi di scrittura riceverà 403 forbidden su ogni operazione di modifica.
3. Copia la chiave. Inizia con tb_live_ e viene mostrata una sola volta.
4. Inviarla come bearer token in ogni richiesta:

curl https://api.tasksboard.com/v1/lists \
  -H "Authorization: Bearer tb_live_…"

Nella stessa scheda trovi l’elenco delle tue chiavi con i relativi permessi, puoi revocarne una e vedere i tuoi webhook. Revoca una chiave appena pensi possa essere compromessa; crearne una nuova richiede pochi secondi.

Gli endpoint principali

Una panoramica delle risorse. La documentazione completa, generata dalla definizione OpenAPI, è nel centro assistenza: Riferimento API TasksBoard.

Account

• GET /me: l’account a cui appartiene la chiave, il suo piano e i permessi della chiave.

Liste

• GET /lists: le tue liste Google Tasks, con shared e boardId.
• POST /lists: crea una lista (title).
• GET /lists/{listId}: una singola lista.

Task

• GET /lists/{listId}/tasks: di default i task aperti; status=completed o all, updatedAfter, dueBefore, dueAfter, includeDeleted.
• POST /lists/{listId}/tasks: crea un task con title, notes, due, labels, assignee, parent (per renderlo un sottotask), previous (per inserirlo dopo un fratello).
• GET /tasks/{taskId}?listId=: un singolo task. Google identifica un task tramite lista e ID, quindi listId è obbligatorio.
• PATCH /tasks/{taskId}: aggiornamento parziale; invia null per cancellare notes, due, labels o assignee; status: "open" riapre un task completato.
• POST /tasks/{taskId}/complete: completalo.
• DELETE /tasks/{taskId}?listId=: eliminarlo.

Board

• GET /boards: le tue board e gli ID delle liste che ciascuna mostra. La board principale è sempre la prima.

Webhook

• GET, POST /webhooks, e GET, PATCH, DELETE /webhooks/{webhookId}.

Creare un task con un’etichetta e un assegnatario si fa così:

curl -X POST https://api.tasksboard.com/v1/lists/LIST_ID/tasks \
  -H "Authorization: Bearer tb_live_…" \
  -H "Content-Type: application/json" \
  -d '{"title": "Invia il report Q3", "due": "2026-10-24",
       "labels": ["❗️Importante"], "assignee": "bob@example.com"}'

L’assegnatario deve essere un collaboratore della lista (o tu stesso). Gli endpoint delle liste restituiscono meta.nextCursor quando c’è altro da recuperare; passalo come cursor con gli stessi filtri.

Webhook: ricevi notifiche quando un task cambia

Il polling è il punto debole dell’API di Google Tasks. Un webhook lo sostituisce: TasksBoard chiama il tuo URL quando un task viene creato, modificato, completato o eliminato.

1. Registra un webhook con gli eventi che ti interessano:

curl -X POST https://api.tasksboard.com/v1/webhooks \
  -H "Authorization: Bearer tb_live_…" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.example.com/tasksboard",
       "events": ["task.created", "task.completed"]}'

2. Salva il secret dalla risposta. Viene restituito una sola volta, solo in quella risposta; puoi anche fornirne uno tuo.
3. Rispondi a ogni notifica con un codice 2xx entro 10 secondi.

Ogni notifica include tre header: X-TasksBoard-Event (il nome dell’evento), X-TasksBoard-Delivery (un ID di notifica) e X-TasksBoard-Signature. Il corpo contiene l’evento, un timestamp createdAt, il numero del tentativo, il task completo sotto data.task e una source: api per una chiamata REST, sync per un cambiamento arrivato tramite lista condivisa, poll per il polling ogni 15 minuti descritto sotto.

Verifica la firma

L’header della firma ha la forma t=<unix seconds>,v1=<hex>, dove v1 è l’HMAC-SHA256 di "<t>.<raw body>" con il tuo secret. Calcola l’HMAC sul corpo della richiesta esattamente come ricevuto, prima di ogni parsing JSON, e rifiuta timestamp troppo vecchi:

const crypto = require("crypto")

function verify(secret, rawBody, header, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")))
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceSeconds) return false
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex")
  return crypto.timingSafeEqual(Buffer.from(parts.v1, "hex"), Buffer.from(expected, "hex"))
}

Riprova e disattivazione

Le notifiche fallite vengono ritentate fino a 3 volte con backoff. Dopo 20 fallimenti consecutivi il webhook viene disattivato (active: false) finché non lo riattivi con PATCH /webhooks/{id} e "active": true. La scheda API nella pagina Team mostra ogni webhook con il suo URL, gli eventi e un badge Attivo o Disabilitato, quindi un endpoint non funzionante è facile da individuare.

Polling per liste non condivise

Da dove arrivano gli eventi dei webhook? Da tre fonti: le scritture dell’API stessa, i cambiamenti propagati sulle liste condivise e, se lo attivi, il polling delle tue altre liste.

Quest’ultimo punto è cruciale. Una modifica fatta in Gmail o nell’app Google Tasks su una lista non condivisa non viene osservata da TasksBoard a meno che qualcosa non controlli la lista. Nella scheda API, attiva controlla le mie liste ogni 15 minuti: TasksBoard allora verificherà quelle liste su quel programma e emetterà eventi con source: "poll". Senza questa opzione, solo le liste condivise e le scritture API generano eventi.

Se ti servono solo i cambiamenti sulle liste condivise dal tuo team, lascia il polling disattivato.

Zapier

Non tutti vogliono scrivere codice. L’app TasksBoard per Zapier si autentica con la stessa chiave API personale e offre:

• Trigger: Nuovo Task, Task Completato. Entrambi effettuano polling con GET /lists/{listId}/tasks e updatedAfter, lo stesso approccio che useresti in uno script personalizzato.
• Azioni: Crea Task, Completa Task, Crea Lista.

L’integrazione con Zapier è in fase di pubblicazione. Una volta elencata, potrai cercare TasksBoard in Zapier, incollare la tua chiave quando richiesto e scegliere una lista. Fino ad allora, l’API REST e i webhook coprono le stesse funzionalità, e i trigger e azioni sopra descritti ti danno un’idea di cosa aspettarti. Per una panoramica più ampia sulle opzioni di automazione, consulta la nostra guida alle integrazioni con Google Tasks.

Prova TasksBoard Team

Liste condivise, ruoli, registro attività e una REST API con webhook, sul Google Tasks che già usi. Un unico pagamento per tutto il team.

Vedi i piani →

A chi è rivolto

L’API è una funzionalità del piano Team, e l’utilizzo è specifico:

• Team con una lista condivisa come fonte di verità. Un webhook su task.completed con source: "sync" scatta quando qualsiasi collaboratore completa un task, indipendentemente dall’app usata. È l’ideale per un messaggio Slack, una riga in Sheets o un aggiornamento ticket.
• Chi gestisce l’integrazione tra strumenti. Moduli, CRM e helpdesk possono creare task con etichetta e assegnatario in una chiamata, e il task appare sulla board della persona giusta e nella sua app Google Tasks.
• Sviluppatori che hanno provato l’API di Google Tasks e si sono fermati al polling, alla configurazione OAuth o alla mancanza di assegnatari. Una chiave, un header, gli ID originali di Google.

Non è pensata per sostituire completamente l’API di Google. Se ti servono solo i tuoi task in uno script personale e hai già un client OAuth, l’API di Google è gratuita e fa il suo lavoro. La nostra guida all’esportazione da Google Tasks copre i casi una tantum.

FAQ

Conclusione

Google Tasks ha un’API, ma senza webhook, senza etichette o assegnatari, e un costo di configurazione che blocca la maggior parte delle piccole automazioni prima ancora che partano. L’API di TasksBoard mantiene gli ID di Google e aggiunge i pezzi mancanti: una chiave personale che crei in un minuto, endpoint per liste, task e board, webhook verificabili, polling opzionale per liste non condivise e un’app per Zapier in arrivo.

Crea una chiave nella scheda API della pagina Team, fai una chiamata GET /lists e il resto segue dal riferimento API.