API do Google Tasks, Webhooks e Zapier: Potencialize sua produtividade

Você quer que uma tarefa seja criada no Google Tasks sempre que um formulário for enviado. Ou uma mensagem no Slack quando um colega concluir uma tarefa da lista compartilhada. Ou um script noturno que registre tarefas atrasadas em uma planilha.

O Google tem uma API para o Tasks, e ela funciona. Mas não tem webhooks, então “quando uma tarefa é concluída” significa verificar periodicamente cada lista. Ela não sabe nada sobre etiquetas, responsáveis ou quadros, porque o Google Tasks não tem esses recursos. E todo script começa com um projeto no Google Cloud, uma tela de consentimento OAuth e uma rotina de atualização de token.

O TasksBoard agora oferece uma API REST pública sobre seus dados do Google Tasks, com chaves de API pessoais, webhooks assinados com HMAC e um app no Zapier. Este guia explica o que ela oferece, como obter uma chave, os endpoints mais úteis, como funcionam webhooks e polling, e para quem isso serve. A API faz parte do plano Team.

O que a API do TasksBoard adiciona ao Google Tasks

A API lê e grava as mesmas listas e tarefas do Google Tasks que você vê no Gmail e no app. Cada ID de lista e tarefa é o mesmo do Google Tasks, então tudo que você criar permanece compatível com o Google Tasks e outras ferramentas que usam a API do Google.

Além disso, ela expõe o que o TasksBoard adiciona:

• Etiquetas e responsáveis como campos próprios. O Google Tasks só armazena título, notas e data de vencimento. O TasksBoard guarda etiquetas e responsáveis dentro das notas (etiquetas na primeira linha, depois 👤 Responsável: <email>). A API lê e grava como labels e assignee, então o texto livre em notes é o que as pessoas veem no quadro.
• Quadros: quais listas cada quadro do TasksBoard exibe.
• Listas compartilhadas: um flag shared em cada lista, e eventos quando um colaborador altera uma tarefa compartilhada.
• Webhooks para task.created, task.updated, task.completed e task.deleted.

URL base: https://api.tasksboard.com/v1. Respostas são JSON sob uma chave data; erros vêm como { "error": { "code", "message", "details" } }, onde code é estável e details nomeia campos inválidos em um 422.

Criando uma chave de API

Chaves são pessoais. Uma chave age como o usuário que a criou: tudo que a pessoa pode fazer no Google Tasks, a chave pode fazer.

1. No TasksBoard, clique no seu avatar e abra Team, depois a aba API (ou vá direto para /team?tab=api).
2. Clique para criar uma chave. Escolha se ela pode escrever; uma chave sem permissão de escrita recebe 403 forbidden em toda operação de gravação.
3. Copie a chave. Ela começa com tb_live_ e só é mostrada uma vez.
4. Envie-a como token bearer em cada requisição:

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

A mesma aba lista suas chaves com seus escopos, permite revogar uma e mostra seus webhooks. Revogue uma chave imediatamente se ela vazar; uma nova leva alguns segundos.

Os principais endpoints

Um rápido tour pelos recursos. A referência completa, gerada da definição OpenAPI, está no centro de ajuda: Referência da API do TasksBoard.

Conta

• GET /me: a conta à qual a chave pertence, seu plano e os escopos da chave.

Listas

• GET /lists: suas listas do Google Tasks, com shared e boardId.
• POST /lists: cria uma lista (title).
• GET /lists/{listId}: uma lista específica.

Tarefas

• GET /lists/{listId}/tasks: tarefas abertas por padrão; status=completed ou all, updatedAfter, dueBefore, dueAfter, includeDeleted.
• POST /lists/{listId}/tasks: cria uma tarefa com title, notes, due, labels, assignee, parent (torna subtarefa), previous (insere após uma irmã).
• GET /tasks/{taskId}?listId=: uma tarefa. O Google endereça tarefas por lista e ID, então listId é obrigatório.
• PATCH /tasks/{taskId}: atualização parcial; envie null para limpar notes, due, labels ou assignee; status: "open" reabre uma tarefa concluída.
• POST /tasks/{taskId}/complete: conclui a tarefa.
• DELETE /tasks/{taskId}?listId=: exclui a tarefa.

Quadros

• GET /boards: seus quadros e os IDs das listas que cada um exibe. O quadro principal sempre vem primeiro.

Webhooks

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

Criar uma tarefa com etiqueta e responsável fica assim:

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

O responsável deve ser um colaborador da lista (ou você). Endpoints de lista retornam meta.nextCursor quando há mais resultados; passe-o de volta como cursor com os mesmos filtros.

Webhooks: seja avisado quando uma tarefa muda

Polling é o ponto fraco da API do Google Tasks. Um webhook substitui isso: o TasksBoard chama sua URL quando uma tarefa é criada, atualizada, concluída ou excluída.

1. Registre um webhook com os eventos desejados:

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. Salve o secret da resposta. Ele só é retornado uma vez, apenas nessa resposta; você também pode fornecer o seu.
3. Responda cada entrega com qualquer código 2xx em até 10 segundos.

Cada entrega traz três cabeçalhos: X-TasksBoard-Event (nome do evento), X-TasksBoard-Delivery (ID da entrega) e X-TasksBoard-Signature. O corpo contém o evento, um timestamp createdAt, o número da tentativa, a tarefa completa em data.task e uma source: api para chamadas REST, sync para mudanças em listas compartilhadas, poll para o polling de 15 minutos descrito abaixo.

Verificando a assinatura

O cabeçalho de assinatura tem a forma t=<unix seconds>,v1=<hex>, onde v1 é o HMAC-SHA256 de "<t>.<raw body>" com seu segredo. Calcule o HMAC sobre o corpo bruto exatamente como recebido, antes de qualquer parsing de JSON, e rejeite timestamps muito antigos:

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"))
}

Retentativas e desativação

Entregas falhas são repetidas até 3 vezes com backoff. Após 20 falhas consecutivas, o webhook é desativado (active: false) até você reativá-lo com PATCH /webhooks/{id} e "active": true. A aba API na página Team mostra cada webhook com sua URL, eventos e um badge Ativo/Desativado, facilitando identificar endpoints problemáticos.

Polling para listas não compartilhadas

De onde vêm os eventos dos webhooks? De três lugares: escritas diretas na API, mudanças em listas compartilhadas e, se ativado, um polling de suas outras listas.

Esse último é importante. Mudanças feitas no Gmail ou no app Google Tasks em listas não compartilhadas não são observadas pelo TasksBoard a menos que alguém olhe a lista. Na aba API, ative verificar minhas listas a cada 15 minutos: o TasksBoard então checa essas listas nesse intervalo e emite eventos com source: "poll". Sem isso, apenas listas compartilhadas e escritas via API geram eventos.

Se só precisa reagir a mudanças nas listas que seu time compartilha, deixe o polling desligado.

Zapier

Nem todo mundo quer escrever código. O app do TasksBoard para Zapier autentica com a mesma chave de API pessoal e oferece:

• Triggers: Nova Tarefa, Tarefa Concluída. Ambos usam GET /lists/{listId}/tasks com updatedAfter, o mesmo padrão que você usaria em um script próprio.
• Actions: Criar Tarefa, Concluir Tarefa, Criar Lista.

A integração com Zapier está sendo publicada. Quando estiver listada, busque por TasksBoard no Zapier, cole sua chave quando pedido e escolha uma lista. Até lá, a API REST e webhooks cobrem o mesmo terreno, e os triggers e actions acima dão uma ideia do que esperar. Para mais opções de automação, veja nosso guia de integrações com Google Tasks.

Experimente o TasksBoard Team

Listas compartilhadas, funções, log de atividades e uma API REST com webhooks, sobre o Google Tasks que você já usa. Uma conta para todo o time.

Ver planos →

Para quem isso serve

A API é um recurso do plano Team, e o fit é específico:

• Times com uma lista compartilhada como fonte da verdade. Um webhook em task.completed com source: "sync" dispara quando qualquer colaborador conclui uma tarefa, em qualquer app que tenha usado. Isso serve para mensagens no Slack, linhas no Sheets ou atualizações de ticket.
• Pessoas de operações integrando ferramentas. Formulários, CRMs e sistemas de suporte podem criar tarefas com etiqueta e responsável em uma chamada, e a tarefa aparece no quadro certo e no app Google Tasks da pessoa.
• Desenvolvedores que tentaram a API do Google Tasks e pararam no polling, configuração OAuth ou falta de responsáveis. Uma chave, um cabeçalho, os próprios IDs do Google.

Não serve para substituir a API do Google completamente. Se só precisa de suas próprias tarefas em um script pessoal e já tem um cliente OAuth, a API do Google é gratuita e resolve. Nosso guia de exportação do Google Tasks cobre casos pontuais.

FAQ

Conclusão

O Google Tasks tem uma API, mas sem webhooks, etiquetas ou responsáveis, e um custo de configuração que impede pequenas automações. A API do TasksBoard mantém os IDs do Google e adiciona o que falta: uma chave pessoal criada em um minuto, endpoints para listas, tarefas e quadros, webhooks verificáveis, polling opcional para listas não compartilhadas e um app no Zapier a caminho.

Crie uma chave na aba API da página Team, faça uma chamada GET /lists, e o resto segue da referência da API.