Google Tasks API и вебхуки: мощные инструменты для автоматизации

Вы хотите, чтобы при отправке формы автоматически создавалась задача в Google Tasks. Или получать уведомление в Slack, когда коллега завершает задачу из общего списка. Или ночной скрипт, который переносит просроченные задачи в таблицу.

У Google есть Tasks API, и он работает. Однако в нём отсутствуют вебхуки, поэтому для отслеживания завершения задач необходимо опрашивать списки по таймеру. API не поддерживает метки, исполнителей и доски, так как их нет в Google Tasks. Каждый скрипт начинается с проекта в Google Cloud, экрана согласия OAuth и рутины обновления токенов.

Теперь TasksBoard предоставляет REST API для работы с вашими данными Google Tasks, включая персональные ключи, вебхуки с HMAC-подписью и интеграцию с Zapier. В этом руководстве вы узнаете: что предлагает API, как получить ключ, основные эндпоинты, работу вебхуков и для кого предназначено это решение. API доступен в Team-плане.

Что TasksBoard API добавляет к Google Tasks

API читает и записывает те же списки и задачи, которые вы видите в Gmail и приложении Google Tasks. Все ID списков и задач являются оригинальными ID Google Tasks, поэтому ваши интеграции остаются совместимыми с Google Tasks и другими инструментами, использующими API Google.

Помимо этого, API раскрывает возможности TasksBoard:

• Метки и исполнители как отдельные поля. Google Tasks хранит только заголовок, заметки и срок, а TasksBoard сохраняет метки и исполнителя внутри заметок (метки на первой строке, затем 👤 Назначено <email>). API читает и записывает их как labels и assignee, оставляя свободный текст в notes для отображения на доске.
• Доски: какие списки отображает каждая доска TasksBoard.
• Общие списки: флаг shared для каждого списка и события при изменениях задач коллегами.
• Вебхуки для событий task.created, task.updated, task.completed и task.deleted.

Базовый URL: https://api.tasksboard.com/v1. Ответы в JSON под ключом data; ошибки возвращаются как { "error": { "code", "message", "details" } }, где code стабилен, а details указывает неверные поля при 422.

Создание API-ключа

Ключи персональные. Ключ действует от имени пользователя, который его создал: всё, что доступно этому пользователю в Google Tasks, доступно и ключу.

1. В TasksBoard нажмите на аватар, откройте Команда, затем вкладку API (или перейдите прямо на /team?tab=api).
2. Создайте ключ. Выберите, может ли он записывать; ключ без права записи получит 403 forbidden на любые запросы на запись.
3. Скопируйте ключ. Он начинается с tb_live_ и показывается только один раз.
4. Передавайте его как bearer-токен в каждом запросе:

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

На этой же вкладке отображаются ваши ключи с их правами, можно отозвать ключ и посмотреть вебхуки. В случае утечки отзовите ключ немедленно, так как новый создаётся за секунды.

Основные эндпоинты

Краткий обзор ресурсов. Полная документация, сгенерированная из OpenAPI-определения, в справочном центре: Справочник TasksBoard API.

Аккаунт

• GET /me: информация об аккаунте, его тарифе и правах ключа.

Списки

• GET /lists: ваши списки Google Tasks с флагами shared и boardId.
• POST /lists: создать список (title).
• GET /lists/{listId}: получить один список.

Задачи

• GET /lists/{listId}/tasks: по умолчанию активные задачи; параметры status=completed или all, updatedAfter, dueBefore, dueAfter, includeDeleted.
• POST /lists/{listId}/tasks: создать задачу с title, notes, due, labels, assignee, parent (сделать подзадачей), previous (вставить после другой задачи).
• GET /tasks/{taskId}?listId=: получить одну задачу. Google обращается к задаче через список и ID, поэтому listId обязателен.
• PATCH /tasks/{taskId}: частичное обновление; передайте null, чтобы очистить notes, due, labels или assignee; status: "open" открывает завершённую задачу.
• POST /tasks/{taskId}/complete: завершить задачу.
• DELETE /tasks/{taskId}?listId=: удалить задачу.

Доски

• GET /boards: ваши доски и ID списков, которые они отображают. Главная доска всегда первая.

Вебхуки

• GET, POST /webhooks, а также GET, PATCH, DELETE /webhooks/{webhookId}.

Пример создания задачи с меткой и исполнителем:

curl -X POST https://api.tasksboard.com/v1/lists/LIST_ID/tasks \
  -H "Authorization: Bearer tb_live_…" \
  -H "Content-Type: application/json" \
  -d '{"title": "Отправить отчёт за Q3", "due": "2026-10-24",
       "labels": ["❗️Важно"], "assignee": "bob@example.com"}'

Исполнитель должен быть участником списка (или вами). Эндпоинты списков возвращают meta.nextCursor, если есть ещё данные; передавайте его как cursor с теми же фильтрами.

Вебхуки: уведомления об изменениях задач

Необходимость опрашивать API является слабым местом Google Tasks. Вебхуки заменяют опрос: TasksBoard вызывает ваш URL при создании, изменении, завершении или удалении задачи.

1. Зарегистрируйте вебхук с нужными событиями:

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. Сохраните secret из ответа. Он показывается только один раз, в этом ответе; можно также указать свой.
3. Отвечайте на каждый запрос любым 2xx-кодом в течение 10 секунд.

Каждое уведомление содержит три заголовка: X-TasksBoard-Event (название события), X-TasksBoard-Delivery (ID доставки) и X-TasksBoard-Signature. Тело включает событие, метку времени createdAt, номер попытки, полные данные задачи в data.task и source: api для REST-вызова, sync для изменений через общий список, poll для 15-минутного опроса (см. ниже).

Проверка подписи

Заголовок подписи имеет вид t=<unix секунды>,v1=<hex>, где v1 представляет собой HMAC-SHA256 от "<t>.<raw body>" с вашим секретом. Вычислите HMAC над исходным телом запроса до любого парсинга JSON и отклоняйте устаревшие метки времени:

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

Повторы и отключение

Неудачные доставки повторяются до 3 раз с задержками. После 20 неудач подряд вебхук отключается (active: false), пока вы не включите его снова через PATCH /webhooks/{id} и "active": true. На вкладке API в разделе Команда отображаются все вебхуки с их URL, событиями и статусом Active или Disabled, так что неработающий эндпоинт легко заметить.

Опрос необщих списков

Откуда берутся события вебхуков? Из трёх источников: запросов к API, изменений в общих списках и, если включено, опроса остальных списков.

Последний пункт важен. Изменения в Gmail или приложении Google Tasks в необщем списке не видны TasksBoard, пока кто-то не посмотрит список. На вкладке API включите опрашивать мои списки каждые 15 минут: TasksBoard будет проверять списки по расписанию и отправлять события с source: "poll". Без этого события генерируются только для общих списков и запросов к API.

Если вам нужны только изменения в общих списках команды, оставьте опрос выключенным.

Zapier

Не все хотят писать код. Приложение TasksBoard для Zapier использует тот же персональный API-ключ и предлагает:

• Триггеры: Новая задача, Задача завершена. Оба используют GET /lists/{listId}/tasks с updatedAfter, как в вашем скрипте.
• Действия: Создать задачу, Завершить задачу, Создать список.

Интеграция с Zapier находится в процессе публикации. Когда она появится в каталоге, ищите TasksBoard в Zapier, вставьте ключ при запросе и выберите список. Пока доступны REST API и вебхуки, а триггеры и действия дают представление о функционале. Подробнее об автоматизации читайте в нашем руководстве по интеграциям Google Tasks.

Попробуйте TasksBoard Team

Общие списки, роли, журнал действий и REST API с вебхуками поверх привычного Google Tasks. Один счёт для всей команды.

Тарифы →

Для кого это

API является функцией Team-плана, но подходит не всем:

• Командам с общим списком как источником истины. Вебхук на task.completed с source: "sync" срабатывает, когда любой участник завершает задачу, в каком бы приложении он ни работал. Это основа для уведомления в Slack, строки в таблице или обновления тикета.
• Специалистам, которые соединяют инструменты. Формы, CRM и службы поддержки могут создавать задачи с меткой и исполнителем одним запросом, и задача появится на доске нужного человека и в его Google Tasks.
• Разработчикам, которые пробовали Google Tasks API и остановились на опросе, настройке OAuth или отсутствии исполнителей. Один ключ, один заголовок, родные ID Google.

API не для полной замены Google Tasks API. Если вам нужны только ваши задачи в личном скрипте и у вас уже есть OAuth-клиент, API Google бесплатен и справится. Наш гид по экспорту Google Tasks покрывает разовые случаи.

FAQ

Заключение

У Google Tasks есть API, но нет вебхуков, меток и исполнителей, а настройка останавливает многие небольшие автоматизации. TasksBoard API сохраняет ID Google и добавляет недостающее: персональный ключ за минуту, эндпоинты для списков, задач и досок, проверяемые вебхуки, опциональный опрос необщих списков и интеграцию с Zapier.

Создайте ключ на вкладке API в разделе Команда, сделайте запрос GET /lists, а остальное смотрите в справочнике API.