Google Tasks API와 웹훅, Zapier 연동: 파워유저를 위한 공개 API 활용법

폼이 제출될 때마다 Google Tasks에 작업이 생성되길 원하시나요? 아니면 팀원이 공유 출시 목록에서 작업을 완료할 때마다 Slack 메시지를 받고 싶으신가요? 또는 매일 밤 지연된 작업을 스프레드시트에 정리하는 스크립트가 필요하신가요?

Google에는 Tasks API가 있고 실제로 작동합니다. 하지만 웹훅이 없어서 “작업이 완료될 때”를 감지하려면 타이머로 매번 목록을 확인해야 합니다. 또한 라벨, 담당자 또는 보드에 대한 정보가 없는데, Google Tasks에는 이런 기능이 없기 때문입니다. 그리고 모든 스크립트는 Google Cloud 프로젝트, OAuth 동의 화면, 토큰 갱신 루틴으로 시작해야 합니다.

TasksBoard는 이제 Google Tasks 데이터 위에 개인 API 키, HMAC으로 서명된 웹훅, Zapier 앱을 포함한 공개 REST API를 제공합니다. 이 가이드에서는 제공하는 기능, 키를 얻는 방법, 가장 많이 사용할 엔드포인트, 웹훅과 폴링 작동 방식, 그리고 이 기능이 필요한 사용자에 대해 설명합니다. 이 API는 팀 플랜의 일부입니다.

TasksBoard API가 Google Tasks에 추가하는 기능

이 API는 Gmail과 Google Tasks 앱에서 보는 것과 동일한 Google Tasks 목록과 작업을 읽고 씁니다. 모든 목록과 작업 ID는 Google Tasks ID이므로, 여러분이 만든 것은 Google Tasks 자체와 Google의 API를 사용하는 다른 도구들과 호환됩니다.

그 위에 TasksBoard가 추가한 기능을 제공합니다:

• 라벨과 담당자를 별도의 필드로 제공. Google Tasks는 제목, 메모, 마감일만 저장하지만, TasksBoard는 메모 안에 라벨과 담당자를 보관합니다(첫 줄에 라벨, 그 다음에 👤 <이메일>에게 할당됨). API는 이를 labels와 assignee로 읽고 쓰므로, notes의 자유 텍스트는 보드에서 사람들이 보는 내용입니다.
• 보드: 각 TasksBoard 보드가 표시하는 목록들.
• 공유 목록: 각 목록의 shared 플래그와 협력자가 공유 작업을 변경할 때의 이벤트.
• task.created, task.updated, task.completed, task.deleted에 대한 웹훅.

기본 URL: https://api.tasksboard.com/v1. 응답은 data 키 아래의 JSON이며, 오류는 { "error": { "code", "message", "details" } } 형태로 반환됩니다. 여기서 code는 안정적이며, 422 상태에서는 details에 유효하지 않은 필드 이름이 포함됩니다.

API 키 생성하기

키는 개인별로 생성됩니다. 키는 생성한 사용자로 동작합니다: Google Tasks에서 그 사람이 할 수 있는 모든 것을 키도 할 수 있습니다.

1. TasksBoard에서 아바타를 클릭하고 팀을 연 다음 API 탭을 엽니다(또는 바로 /team?tab=api로 이동).
2. 키 생성을 클릭합니다. 쓰기 권한을 부여할지 선택하세요; 쓰기 범위가 없는 키는 모든 쓰기 요청에 403 forbidden을 받습니다.
3. 키를 복사합니다. tb_live_로 시작하며 한 번만 표시됩니다.
4. 모든 요청에 베어러 토큰으로 전송합니다:

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

같은 탭에서 키와 그 범위를 확인할 수 있으며, 키를 취소하거나 웹훅을 볼 수 있습니다. 키가 유출되었을 가능성이 있다면 즉시 취소하세요; 새 키는 몇 초 안에 생성됩니다.

주요 엔드포인트

리소스에 대한 간략한 소개입니다. 전체 참조 문서는 OpenAPI 정의에서 생성되며, 도움말 센터에서 확인할 수 있습니다: TasksBoard API 참조.

계정

• GET /me: 키가 속한 계정, 그 계정의 플랜 및 키의 범위.

목록

• GET /lists: shared 및 boardId와 함께 Google Tasks 목록.
• 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}: 부분 업데이트; notes, due, labels 또는 assignee를 지우려면 null을 보냅니다; 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로 다시 전달하세요.

웹훅: 작업이 변경될 때 알림 받기

폴링은 Google Tasks API의 약점입니다. 웹훅은 이를 대체합니다: 작업이 생성, 업데이트, 완료 또는 삭제될 때 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. 모든 전송에 10초 이내에 2xx로 응답하세요.

각 전송에는 세 가지 헤더가 있습니다: X-TasksBoard-Event(이벤트 이름), X-TasksBoard-Delivery(전송 ID), X-TasksBoard-Signature. 본문에는 이벤트, createdAt 타임스탬프, 시도 횟수, data.task 아래의 전체 작업, 그리고 source: REST 호출의 경우 api, 공유 목록을 통해 도착한 변경의 경우 sync, 아래 설명된 15분 폴링의 경우 poll이 포함됩니다.

서명 확인

서명 헤더는 t=<유닉스 초>,v1=<16진수> 형태이며, 여기서 v1은 여러분의 비밀키로 "<t>.<원본 본문>"의 HMAC-SHA256입니다. JSON 파싱 전에 받은 원본 요청 본문에 대해 HMAC을 계산하고, 너무 오래된 타임스탬프는 거부하세요:

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, 이벤트 및 활성 또는 비활성 배지와 함께 표시하므로, 죽은 엔드포인트를 쉽게 발견할 수 있습니다.

공유되지 않은 목록 폴링

웹훅 이벤트는 어디에서 오나요? 세 곳에서 옵니다: API 자체의 쓰기, 공유 목록에서 전파된 변경 사항, 그리고 켜면 다른 목록의 폴링입니다.

마지막 것이 중요합니다. 공유되지 않은 목록에서 Gmail 또는 Google Tasks 앱에서 만든 변경 사항은 목록을 확인하지 않는 한 TasksBoard에서 관찰되지 않습니다. API 탭에서 15분마다 내 목록 폴링을 켜세요: TasksBoard는 그 일정에 따라 목록을 확인하고 source: "poll"로 이벤트를 발생시킵니다. 이것 없이는 공유 목록과 API 쓰기만 이벤트를 생성합니다.

팀이 공유하는 목록의 변경 사항에만 반응해야 한다면 폴링을 끄세요.

Zapier

모두가 코드를 작성하고 싶어하는 것은 아닙니다. Zapier용 TasksBoard 앱은 동일한 개인 API 키로 인증하며 다음을 제공합니다:

• 트리거: 새 작업, 작업 완료. 둘 다 updatedAfter와 함께 GET /lists/{listId}/tasks를 폴링하며, 여러분의 스크립트에서 사용할 것과 같은 관용구입니다.
• 액션: 작업 생성, 작업 완료, 목록 생성.

Zapier 통합은 현재 출판 중입니다. 목록에 올라가면 Zapier에서 TasksBoard를 검색하고, 키를 묻는 곳에 붙여넣고 목록을 선택하세요. 그 전에는 REST API와 웹훅이 같은 범위를 다루며, 위의 트리거와 액션이 기대할 내용을 알려줍니다. 자동화 옵션에 대한 더 넓은 보기는 Google Tasks 통합 가이드를 참조하세요.

TasksBoard 팀 체험하기

이미 사용 중인 Google Tasks 위에 공유 목록, 역할, 활동 로그 및 웹훅이 있는 REST API를 제공합니다. 전체 팀을 위한 하나의 청구서.

플랜 보기 →

이 기능이 필요한 사람

이 API는 팀 플랜 기능이며, 특정한 경우에 적합합니다:

• 진실의 원천으로 공유 목록이 있는 팀. source: "sync"와 함께 task.completed에 대한 웹훅은 협력자가 작업을 완료할 때마다 발생하며, 어떤 앱을 사용했는지에 관계없습니다. Slack 메시지, Sheets의 행 또는 티켓 업데이트를 위한 훅입니다.
• 도구를 연결하는 운영 담당자. 양식, CRM 및 지원 데스크는 한 번의 호출로 라벨과 담당자가 있는 작업을 생성할 수 있으며, 작업은 올바른 사람의 보드와 Google Tasks 앱에 나타납니다.
• Google Tasks API를 시도한 개발자들이 폴링, OAuth 설정 또는 담당자 부족에서 멈춘 경우. 하나의 키, 하나의 헤더, Google의 자체 ID.

Google의 API를 완전히 대체하기 위한 것은 아닙니다. 개인 스크립트에서 자신의 작업만 필요하고 이미 OAuth 클라이언트가 있다면, Google의 API는 무료이며 그 일을 합니다. 일회성 경우는 Google Tasks 내보내기 가이드에서 다룹니다.

FAQ

결론

Google Tasks에는 API가 있지만 웹훅, 라벨 또는 담당자가 없으며, 대부분의 작은 자동화를 시작하기 전에 멈추게 하는 설정 비용이 있습니다. TasksBoard API는 Google의 ID를 유지하고 누락된 부분을 추가합니다: 1분 안에 생성할 수 있는 개인 키, 목록, 작업 및 보드를 위한 엔드포인트, 확인할 수 있는 웹훅, 공유되지 않은 목록을 위한 선택적 폴링, 그리고 출시 예정인 Zapier 앱.

팀 페이지의 API 탭에서 키를 생성하고, GET /lists 호출을 한 번 하면, 나머지는 API 참조에서 따라옵니다.