TaskFlow 개발자 문서
TaskFlow 의 기본 기능은 그대로 두고, 우리 조직에 필요한 화면·서버 동작·자동화·외부 연동을 직접 더하는 방법입니다.
SDK 판 2 · 마지막 갱신 2026-10-24 · TypeScript 형식 정의(taskflow-sdk.d.ts) · 확장·자동화·웹훅·연동 키는 조직의 관리자·경영관리자가 만들고, 직원은 설정 › 플러그인에서 설치해 씁니다.
무엇을 만들 수 있나
| 하고 싶은 일 | 쓰는 것 |
|---|---|
| "완료되면 만든 사람에게 알려 줘" 같은 반복 일 | 자동화 규칙 |
| 우리 조직만의 표·입력 화면·대시보드 카드 | 확장 화면 |
| 사내 ERP·CRM API 와 주고받기(키 필요) | 확장 화면 + 서버 동작 + 비밀 값 |
| 업무가 바뀌면 바깥 시스템도 바로 알기 | 웹훅 |
| 바깥 시스템에서 업무를 만들거나 조회 | REST API(연동 키) |
| 결재 문서·프로젝트에 우리 회사만의 칸·화면 더하기 | 덧붙이기(결재 문서 구역·프로젝트 탭) + 확장 전용 표 |
| "금액이 크면 재무합의를 넣어라" 같은 결재 규칙 | 저장 전 규칙(서버 동작) |
| 전자결재 화면을 우리 방식으로 바꾸기 | 원본 대신 쓰기(복제 시작본) — 언제든 원본으로 되돌림 |
5분 시작
- 설정 › 확장 만들기 › 새 확장 — 이름과 시작 틀(예: 업무 상세 탭)을 고릅니다.
- 코드 탭에서 HTML 을 고치면 오른쪽 미리보기에 바로 보입니다(저장 전 코드, 실제 데이터).
- 자리·권한 탭에서 붙을 자리와 필요한 권한만 고릅니다.
- 초안 저장 → 게시. 게시 창에서 자리·권한·바깥 주소를 확인합니다.
- 직원은 설정 › 플러그인 › 우리 조직이 만든 확장에서 설치합니다(관리자는 '조직 전원에게 설치'도 가능).
<div class="tf-stack">
<h2>내 진행 업무</h2>
<table class="tf-table"><tbody id="rows"></tbody></table>
</div>
<script>
taskflow.ready().then(async (ctx) => {
const list = await taskflow.tasks.list({ mine: true, status: 'in-progress' });
const tbody = document.getElementById('rows');
if (!list.length) { tbody.innerHTML = '<tr><td class="tf-empty">진행 중인 업무가 없습니다</td></tr>'; return; }
for (const t of list) {
const tr = document.createElement('tr'), td = document.createElement('td'), a = document.createElement('a');
a.href = '#'; a.textContent = t.title; // 사람이 쓴 글은 textContent 로
a.onclick = (e) => { e.preventDefault(); taskflow.ui.openTask(t.id); };
td.appendChild(a); tr.appendChild(td); tbody.appendChild(tr);
}
});
</script>
매니페스트
확장이 어디에 붙고 무엇을 할 수 있는지 적는 JSON 입니다. 확장 만들기 화면의 '자리·권한'·'서버 동작' 탭이 이 값을 만듭니다.
{
"slots": [
{ "type": "task-tab", "title": "고객 정보", "icon": "users", "height": 480 }
],
"permissions": ["tasks:read", "tasks:write"],
"network": ["https://api.example.com"],
"server": {
"actions": ["syncCustomer"],
"schedules": [{ "action": "syncCustomer", "every": "1h" }]
},
"tables": { "customers": { "label": "거래처", "columns": { "name": "text", "taskId": "task" } } },
"hooks": [{ "event": "approval.beforeSubmit", "action": "checkAmount" }]
}
| 칸 | 설명 |
|---|---|
slots | 붙는 자리. 종류마다 하나씩, 1개 이상. title 40자, height 120~1200(px, 페이지 자리는 화면 전체) |
permissions | 요청하는 권한. 필요한 것만 — 게시·설치 화면에 그대로 보입니다 |
network | 화면·서버 코드가 통신할 바깥 주소(https, 도메인, 10개까지). https://*.example.com 처럼 하위 도메인 전체도 가능. 여기 없는 주소로는 어떤 방법으로도 보낼 수 없습니다 |
server | (선택) 서버 동작 이름 목록과 예약. 서버 동작 |
tables | (선택) 확장 전용 표 — 정한 칸·종류만 저장됩니다. 확장 전용 표 |
hooks | (선택) 저장 전 규칙 — 원본 화면이 저장 직전에 부를 서버 동작. 저장 전 규칙 |
slots[].replaces | (선택, page 자리만) 원본 대신 쓸 기능. 지금은 "approval"(전자결재). 원본 대신 쓰기 |
붙는 자리
| type | 위치 | 문맥(ctx) |
|---|---|---|
page | 왼쪽 메뉴에 버튼, 넓은 화면 하나(모바일은 위 메뉴) | 사용자 |
task-tab | 업무 상세 창의 탭 | 사용자 + ctx.task |
home-card | 홈 화면 카드 | 사용자 |
task-action | 업무 오른쪽 클릭(모바일 길게 누르기) 메뉴 → 작은 창. 끝나면 taskflow.ui.close() | 사용자 + ctx.task |
approval-section | 결재 문서 상세의 신청 내용 아래 구역(권한 approval:read 필요) | 사용자 + ctx.approval |
project-tab | 프로젝트 상세의 탭(모바일은 상세 화면 안 구역, 권한 projects:read 필요) | 사용자 + ctx.project |
권한
권한은 확장이 요청할 수 있는 범위일 뿐이고, 실제로는 언제나 지금 쓰는 사람이 볼 수 있고 고칠 수 있는 것까지만 됩니다.
| 권한 | 할 수 있는 일 |
|---|---|
tasks:read | 업무 목록·내용 읽기 |
tasks:write | 업무 만들기, 상태·담당·마감·필드 고치기(만든 사람·담당자·관리자일 때) |
projects:read | 프로젝트 목록 읽기 |
users:read | 구성원 이름·부서·직책 읽기 |
approval:read | 내가 올렸거나 결재·참조로 지정된 결재 문서와 양식 읽기(경영관리자는 모든 상신 문서) |
approval:act | 내 차례인 문서 승인·반려 — 원본 결재 화면과 같은 처리(다음 결재자 알림·조직 규칙 포함) |
| (없음) | 확장 저장소(taskflow.data)·화면 동작(taskflow.ui)·서버 동작 부르기는 권한 없이 됩니다 |
SDK 참조 — window.taskflow
확장 화면에는 SDK 가 미리 들어 있습니다. 모든 함수는 Promise 를 돌려주고, 실패하면 한국어 메시지를 담은 Error 를 던집니다.
문맥
| 함수 | 설명 |
|---|---|
taskflow.ready() | 문맥 ctx 를 받을 때까지 기다립니다. { user:{id,name,role,isManager}, task?, approval?, project?, replaces?, tables, slot, mobile, dark, permissions, extension:{id,name,version} } |
taskflow.onContext(fn) | 문맥이 바뀔 때마다(업무 상태가 바뀌는 등) fn(ctx) |
taskflow.context | 마지막으로 받은 문맥 |
업무 · 프로젝트 · 구성원
| 함수 | 돌려주는 값 |
|---|---|
tasks.list({ mine, status, projectId, search, includeDone, ids, limit }) | 업무 배열(기본 완료 제외, limit 최대 200). status 는 todo·accepted·in-progress·done 또는 배열 |
tasks.get(id) | 업무 하나 + description |
tasks.create({ title, description, status, priority, assignees, dueDate, startDate, projectId, customFields }) | { id }. 담당자를 안 주면 만든 사람 |
tasks.update(id, { title, description, status, priority, assignees, dueDate, startDate, progress, customFields }) | 고친 업무. customFields 는 합쳐집니다 |
projects.list() | [{ id, name, status, color, startDate, endDate }] |
users.list() | [{ id, name, color, department, position }] |
업무 모양: { id, title, status, statusLabel, priority, assignees, managers, followers, startDate, dueDate, progress, projectId, activityId, parentId, taskType, customFields, createdBy, createdAt, updatedAt, completedAt } — 날짜는 YYYY-MM-DD, 우선순위는 low·medium·high.
확장 저장소
| 함수 | 설명 |
|---|---|
data.get(모음, id, { scope }) | 값 하나(없으면 null) |
data.list(모음, { scope, limit }) | [{ id, data, updatedAt, updatedBy }], 최근 바뀐 순, 최대 1000 |
data.query(표, { 칸: 값 }, { scope, limit, order }) | 같은 값인 행 찾기 → [{ id, data, updatedAt, updatedBy }]. 값은 글자·숫자·true/false, order: 'oldest' 면 오래된 순 |
data.set(모음, id, 값, { scope }) | 저장(있으면 덮어씀). 값 하나 250KB 이하. tables 에 정한 표면 정한 칸·종류만 |
data.remove(모음, id, { scope }) | 지우기 |
scope 기본 'org'(조직 공용) · 'user' = 나만 보는 칸. 모음 이름은 영문·숫자·_.- 64자, id 는 128자까지. 확장마다 2만 건까지.
화면 동작 · 서버
| 함수 | 설명 |
|---|---|
ui.toast(글) | 앱 아래 짧은 알림 |
ui.openTask(id) | 업무 상세 열기 |
ui.openApproval(id) | 원본 결재 화면에서 문서 열기(null 이면 결재 홈). 원본 대신 쓰는 중이어도 원본을 엽니다 |
ui.navigate(tab) | dashboard·tasks·projects·chat·approval·attendance·expense·settings |
ui.openUrl(url) | https 주소를 새 창으로 — 사용자에게 주소를 보여 주고 허락을 받습니다. <a href="https://…"> 클릭도 같은 길로 갑니다 |
ui.confirm(글) | 확인 창 → true/false |
ui.close() | 업무 메뉴 창 닫기 |
server.call(동작, 입력) | 서버 동작 실행 → 결과. 서버 동작 |
기본 모양
앱과 같은 느낌의 클래스와 색 변수가 들어 있습니다. 변수로 쓰면 다크 모드가 저절로 맞습니다.
tf-card | 흰 면·1px 선·둥근 16px 카드 |
tf-btn / tf-btn tf-btn-primary | 보조 버튼 / 주 버튼(검정 알약) |
tf-input tf-select tf-textarea tf-label | 입력 |
tf-table · tf-chip(.success .warning .error) | 표 · 꼬리표 |
tf-row · tf-stack · tf-muted · tf-empty | 가로 줄 · 세로 간격 · 보조 글 · 빈 상태 |
--text-primary --text-secondary --text-muted --border --bg-secondary --accent-blue | 색 변수 |
권장: 글자 12px 이상, 카드 속 카드 대신 여백·선 한 줄, 이모지 대신 글, 상태에만 색. 예시 자료를 지어내지 말고 없으면 tf-empty 로 할 일 하나를 보여 주세요.
실행 환경 규칙
확장 화면은 앱과 분리된 샌드박스(불투명 출처 iframe)에서 돕니다. 그래서 아래는 되지 않거나 다르게 동작합니다.
| 안 되는 것 | 대신 |
|---|---|
localStorage·sessionStorage·쿠키 | taskflow.data(scope:'user' 면 개인 칸) |
앱 화면(window.parent)·로그인 정보 접근 | SDK 함수 |
매니페스트에 없는 주소로 fetch·이미지·폼 보내기 | network 에 주소 추가 후 다시 게시 |
새 창(window.open)·자기 페이지 이동 | taskflow.ui.openUrl(사용자 확인). 다른 주소로 이동하면 확장이 멈춥니다 |
| 스크립트 불러오기 | cdn.jsdelivr.net · cdnjs.cloudflare.com · unpkg.com 만 가능 |
alert·confirm | taskflow.ui.toast·taskflow.ui.confirm |
기존 기능 바꾸기
TaskFlow 의 기본 기능(업무·결재·프로젝트…) 코드와 데이터는 고치지 않습니다. 대신 두 가지 방법으로 바꿉니다. 어느 쪽이든 원본은 그대로 남아 언제든 돌아갈 수 있습니다.
| 방법 | 무엇을 | 되돌리기 |
|---|---|---|
| ① 덧붙이기 | 원본 화면의 자리(approval-section·project-tab·task-tab…)에 화면을 붙이고, 추가 데이터는 확장 전용 표에 담습니다. 저장 전 규칙으로 결재 요청·승인·반려 직전에 막기·확인·결재자 추가를 합니다. | 확장을 끄면 원본 그대로. 표의 데이터는 남습니다 |
| ② 원본 대신 쓰기 | 원본을 본뜬 화면을 확장으로 만들어, 사람마다(또는 조직 기본으로) 원본 메뉴 자리에 씁니다. 처리는 결재 SDK — 원본과 같은 함수입니다. | 화면 위 [원본으로 되돌리기] 한 번. [원본 화면 보기]로 잠깐 오가기도 됩니다 |
customFields 로 읽고 씁니다).확장 만들기 › 새 확장의 기존 기능 바꾸기 시작 틀: 결재 문서에 거래처 정보 구역 · 프로젝트 위험 관리 탭 · 결재 규칙(금액이 크면 재무합의 추가) · 전자결재 복제본(원본 대신 쓰기).
확장 전용 표
"tables": {
"vendor_info": { "label": "거래처 정보",
"columns": { "docId": "approval", "vendor": "text", "bizNo": "text", "amount": "number", "checked": "boolean" } }
}
칸 종류: text · number · boolean · date(YYYY-MM-DD) · datetime(ISO) · json · 연결 칸 task · approval · project · user(원본 기록의 id). 표 20개, 표마다 칸 50개까지. 표 이름은 영문 소문자로 시작.
// 결재 문서 구역에서 — 그 문서에 이어 둔 거래처 정보 읽고 쓰기
const ctx = await taskflow.ready();
const row = await taskflow.data.get('vendor_info', ctx.approval.id);
await taskflow.data.set('vendor_info', ctx.approval.id, { docId: ctx.approval.id, vendor: 'ACME', amount: 1200000 });
// 조건으로 찾기
const open = await taskflow.data.query('risks', { projectId: ctx.project.id, closed: false });
정하지 않은 칸이나 종류가 틀린 값은 Error 로 거절됩니다(화면 SDK·서버 SDK 같은 규칙). 표로 정하지 않은 모음은 예전처럼 자유 형식입니다. 확장 만들기 › 데이터 표에서 행을 보고 지우고 CSV 로 내려받습니다.
저장 전 규칙
원본 결재 화면이 그 순간 직전에 확장의 서버 동작을 부릅니다. 게시된 확장이면 조직 전체에 적용됩니다(설치와 무관 — 설치를 지워 규칙을 피할 수 없게). 규칙이 문서 내용을 받으므로 권한 approval:read 가 필요하고, 게시 창에 규칙 목록이 보입니다.
| event | 언제 | 돌려줄 수 있는 것 |
|---|---|---|
approval.beforeSubmit | 기안자가 [결재 요청]을 누르면 | block · warn · addSteps |
approval.beforeApprove | 결재자가 [결재(승인)]을 누르면(원본·대신 쓰는 화면·모바일 알림 창 모두) | block · warn |
approval.beforeReject | 결재자가 [반려]를 누르면 | block · warn |
// 매니페스트: "server": { "actions": ["checkAmount"] }, "hooks": [{ "event": "approval.beforeSubmit", "action": "checkAmount" }]
action('checkAmount', async (input) => {
// input = { event, doc: { id, title, docType, formId, status, amount, formData, drafterId, drafterDept, contentText,
// steps: [{ stepOrder, kind, approverId, state }] }, formTitle?, opinion?, step?, actorId? }
const doc = input.doc;
if (!doc.amount || doc.amount <= 1000000) return {}; // 통과
if (!doc.formData.reason) return { block: '100만 원이 넘으면 사유를 적어 주세요.' }; // 막기
return {
warn: '재무팀 합의가 자동으로 추가됩니다.', // 사람에게 확인
addSteps: [{ kind: 'finance_agree', approverId: 'user-7', position: 'end' }] // 결재선에 추가
};
});
kind = approval(결재)·agree(합의)·finance_agree(재무합의)·reference(참조), position = end(기본)·start·beforeLast. 이미 있는 사람·쓸 수 없는 계정은 더하지 않고, 한 번에 5명까지. 규칙을 확인하지 못하면(오류·10초 초과) 막지 않고 건너뛰며 사용자에게 알립니다 — 확장 때문에 결재가 멈추지 않게. 저장 전 규칙은 화면 단계의 규칙이라 REST API 처럼 화면을 거치지 않는 경로에는 적용되지 않습니다.
원본 대신 쓰기
{ "slots": [{ "type": "page", "title": "전자결재", "icon": "file-check", "replaces": "approval" }],
"permissions": ["approval:read", "approval:act", "users:read"] }
- 게시·설치하면 처음엔 원본과 나란히 왼쪽 메뉴에 따로 생깁니다(둘 다 그대로 동작).
- 쓰는 사람이 확장 화면 위 [전자결재 메뉴를 이 화면으로] 또는 설정 › 플러그인의 '원본 대신 쓰기'를 켜면, 전자결재 메뉴에서 이 화면이 열립니다.
- 화면 위에는 늘 [원본 화면 보기](잠깐)·[원본으로 되돌리기](계속)가 붙습니다. 결재 알림을 눌러 연 문서와
ui.openApproval은 원본 상세로 엽니다. - 관리자는 설정 › 플러그인에서 '조직 기본 화면으로'를 켤 수 있습니다 — 따로 고르지 않은 사람 모두의 기본이 되고, 각자 원본으로 되돌릴 수 있습니다.
대체할 수 있는 기능은 처리 함수를 SDK 로 열어 둔 것만입니다(지금은 전자결재). 기안 작성처럼 SDK 에 없는 일은 taskflow.ui.openApproval(null) 로 원본 화면에 연결하세요.
결재 SDK
| 함수 | 설명 |
|---|---|
approval.list({ box, limit }) | box = need(결재할)·soon(예정)·going(처리 후 진행 중)·cc(참조)·drafted(내가 올린)·archive(보관함). 원본 결재함과 같은 분류. approval:read |
approval.get(id) | 문서 + steps[{ stepOrder, kind, kindLabel, approverId, state, stateLabel, opinion, actedAt }] · myTurn · content(정리된 HTML) · attachments · comments |
approval.forms() | 사용 중인 양식 [{ id, title, docType, category, fields }] |
approval.approve(id, 의견) | 승인 → { ok, message }. 처리 전에 매번 앱이 사용자에게 확인 창을 띄웁니다(확장이 사람 모르게 결재하지 못하게). 원본과 같은 처리: 다시 읽어 차례 확인 → 저장 전 규칙 → 다음 결재자 알림·완료 처리. approval:act |
approval.reject(id, 의견) | 반려(의견 필수). 차례가 아니거나 규칙이 막으면 Error(code: NOT_ALLOWED·BLOCKED·CANCELED) |
문서 모양: { id, docNumber, title, docType, formId, status, statusLabel, amount, formData, drafterId, drafterDept, currentStep, createdAt, submittedAt, completedAt }. 규칙의 확인 요청(warn)은 확장 칸 안의 확인 창으로 사람에게 묻습니다.
서버 동작
API 키가 필요한 호출이나 정해진 시간마다 자료를 모으는 일처럼 브라우저에서 하면 안 되는 일을 서버에서 돌립니다. 코드는 TaskFlow 서버의 격리된 자바스크립트 실행기에서 돌고, 부른 사람의 권한으로만 동작합니다.
- 매니페스트
server.actions에 동작 이름을 적습니다(영문 소문자로 시작, 2~41자). - 설정 › 확장 만들기 › 서버 동작 탭에 코드를 씁니다.
- 필요한 키는 같은 탭의 비밀 값에 넣습니다.
- 시험 실행으로 확인한 뒤 게시합니다.
// 고객 정보를 사내 CRM 에서 가져와 업무 필드에 넣는다
action('syncCustomer', async (input, ctx) => {
const task = await taskflow.tasks.get(input.taskId);
const r = await taskflow.http.fetch('https://api.example.com/customers?name=' + encodeURIComponent(task.customFields.company || ''), {
headers: { Authorization: 'Bearer ' + taskflow.secrets.CRM_API_KEY },
});
if (!r.ok) throw new Error('CRM 응답 ' + r.status);
const c = r.json && r.json[0];
if (!c) return { found: false };
await taskflow.tasks.update(task.id, { customFields: { customerGrade: c.grade, customerOwner: c.owner } });
taskflow.log('갱신', task.id, c.grade);
return { found: true, grade: c.grade };
});<button class="tf-btn tf-btn-primary" id="sync">CRM 에서 가져오기</button>
<script>
taskflow.ready().then((ctx) => {
document.getElementById('sync').onclick = async () => {
try {
const r = await taskflow.server.call('syncCustomer', { taskId: ctx.task.id });
taskflow.ui.toast(r.found ? '고객 등급: ' + r.grade : 'CRM 에 없는 고객입니다');
} catch (e) { taskflow.ui.toast(e.message); }
};
});
</script>서버 SDK
| 이름 | 설명 |
|---|---|
action(이름, async (input, ctx) => 결과) | 동작 등록. ctx = { user:{id,name}, extension:{id,version}, mode } — mode 는 'user'·'draft'(시험)·'schedule'(예약) |
taskflow.tasks · projects · users · data | 화면 SDK 와 같은 함수(data.query 포함, tables 검사도 같음. 서버의 data.query 는 한 번에 100행까지) |
taskflow.http.fetch(url, { method, headers, body }) | { status, ok, contentType, text, json }. 매니페스트 network 의 https 주소만, 리다이렉트는 따라가지 않음 |
taskflow.secrets.이름 | 비밀 값(읽기 전용) |
taskflow.log(...) · console.log | 실행 기록에 남는 로그(시험 실행·관리자에게 보임) |
서버 코드에는 fetch·require·import·파일·환경 변수가 없습니다. 바깥 통신은 taskflow.http.fetch 하나뿐입니다.
비밀 값
API 키·토큰처럼 코드에 적으면 안 되는 값입니다. 확장 만들기 › 서버 동작 › 비밀 값에서 관리자가 넣고, 넣은 뒤에는 이름만 보입니다. 서버 코드만 taskflow.secrets.이름 으로 읽고, 화면 코드에는 전달되지 않습니다. 이름은 영문 대문자로 시작(CRM_API_KEY), 확장마다 20개까지.
예약 실행
"server": { "actions": ["collectDaily"], "schedules": [{ "action": "collectDaily", "every": "1d" }] }
간격은 15m·30m·1h·6h·1d, 확장마다 3개까지. 예약 실행은 게시한 사람 이름으로 돌고, 비밀 업무는 보이지 않으며, 업무 읽기·만들기와 저장소·바깥 통신만 됩니다(업무 고치기는 사람이 부를 때만). 게시한 사람이 퇴사하면 멈추니 다른 관리자가 다시 게시하세요.
자동화 규칙
설정 › 자동화에서 문장처럼 만듭니다. 앱 AI 에게 "완료되면 만든 사람에게 알려 줘"처럼 말해도 됩니다. 아래는 규칙의 모양입니다.
{
"name": "긴급 업무는 바로 접수",
"event": "task.created",
"event_params": {},
"conditions": [{ "field": "title", "op": "contains", "value": "긴급" }],
"actions": [
{ "type": "set_status", "value": "accepted" },
{ "type": "notify", "to": ["assignees", "managers"], "message": "긴급 업무: {{title}}" }
]
}
| 구분 | 값 |
|---|---|
사건 event | task.created · task.status_changed(from·to) · task.completed · task.assigned(user) · task.priority_changed(to) · task.due_changed · task.field_changed(field) · task.due_soon(days) · task.overdue |
조건 field | status · priority · assignees · title · description · project_id · task_type · created_by · custom:필드열쇠 |
조건 op | eq · neq · contains · not_contains · empty · not_empty |
| 업무 바꾸기 | set_status·set_priority{value} · add_assignee·add_manager·add_follower{value:사용자} · set_due{days} · set_field{key, value} |
| 바깥 일 | notify{to:[assignees·managers·followers·creator·사용자], message} · add_note{content} · add_todo{items} · create_task{title, assignees:['same'|사용자], due_days, priority, subtask} · webhook{webhook_id} |
| 글 자리표시 | {{title}} {{status}} {{priority}} {{due_date}} {{id}} {{field:열쇠}} |
자동화가 만든 변경은 다시 자동화를 부르지 않습니다. 비밀 업무는 자동화하지 않습니다. 마감 사건은 1분마다 확인하고 같은 업무·같은 마감일에는 한 번만 실행합니다(한국 시간 기준). 조직마다 규칙 100개까지.
웹훅
설정 › 웹훅·연동 키에서 받는 주소(https 공개 도메인)와 사건을 고릅니다. 받는 쪽은 8초 안에 2xx 로 답하면 성공입니다. 실패하면 1분·5분·30분·2시간 뒤 다시 보내고 5번 실패하면 멈춥니다. 50번 연속 실패한 웹훅은 꺼집니다.
사건: task.createdtask.updatedtask.status_changedtask.completedtask.assignedtask.priority_changedtask.due_changedtask.field_changedtask.deletedtask.due_soontask.overdue 그리고 시험 발송 ping, 자동화가 보낸 automation.rule
POST https://hooks.example.com/taskflow
Content-Type: application/json
X-Taskflow-Event: task.status_changed
X-Taskflow-Delivery: 1842
X-Taskflow-Timestamp: 1792687200
X-Taskflow-Signature: sha256=5b1f…
{ "event": "task.status_changed", "occurredAt": "2026-10-23T01:20:00+00:00",
"task": { "id": "TASK-…", "title": "고객사 계약서 검토", "status": "done", "priority": "high", "assignees": ["user-12"], "dueDate": "2026-10-24", "customFields": { … } },
"previous": { "status": "in-progress", "priority": "high", "assignees": ["user-12"], "dueDate": "2026-10-24" } }
서명 확인
X-Taskflow-Signature = sha256= + HMAC-SHA256(서명 비밀, 타임스탬프 + "." + 받은 본문 원문). 본문을 다시 JSON 으로 만들지 말고 받은 그대로 검증하세요. 서명 비밀은 웹훅의 [서명 비밀]에서 봅니다.
const crypto = require('crypto');
function verifyTaskflow(headers, rawBody, secret) {
const ts = headers['x-taskflow-timestamp'];
const sig = headers['x-taskflow-signature'] || '';
const want = 'sha256=' + crypto.createHmac('sha256', secret).update(ts + '.' + rawBody).digest('hex');
const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
return fresh && sig.length === want.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(want));
}import hmac, hashlib, time
def verify_taskflow(headers, raw_body: bytes, secret: str) -> bool:
ts = headers.get('X-Taskflow-Timestamp', '')
sig = headers.get('X-Taskflow-Signature', '')
want = 'sha256=' + hmac.new(secret.encode(), (ts + '.').encode() + raw_body, hashlib.sha256).hexdigest()
return abs(time.time() - int(ts or 0)) < 300 and hmac.compare_digest(sig, want)function verify_taskflow(string $rawBody, string $secret): bool {
$ts = $_SERVER['HTTP_X_TASKFLOW_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_TASKFLOW_SIGNATURE'] ?? '';
$want = 'sha256=' . hash_hmac('sha256', $ts . '.' . $rawBody, $secret);
return abs(time() - (int)$ts) < 300 && hash_equals($want, $sig);
}같은 배달이 두 번 올 수 있습니다(재시도). X-Taskflow-Delivery 로 중복을 거르세요. 비밀 업무는 보내지 않습니다.
REST API
바깥 프로그램(n8n·사내 서버 등)이 쓰는 API 입니다. 설정 › 웹훅·연동 키에서 연동 키를 만들 때 범위를 고르고, 같은 화면에 표시되는 API 주소로 부릅니다. 키는 만들 때 한 번만 보입니다.
curl -H "x-taskflow-api-key: tfk_…" "<API 주소>/tasks?status=in-progress&limit=20"
| 요청 | 범위 | 설명 |
|---|---|---|
GET /me | — | 키 이름·범위 확인 |
GET /tasks?status=&projectId=&assignee=&query=&limit= | tasks:read | 업무 목록(최신순, 최대 200) |
GET /tasks/:id | tasks:read | 업무 하나 |
POST /tasks | tasks:write | 업무 만들기. source.type + source.externalId 가 같으면 새로 만들지 않고 기존 업무(duplicate:true) |
PATCH /tasks/:id | tasks:write | 상태·우선순위·담당·마감·필드 고치기 |
POST /tasks/:id/archive | tasks:write | 보관({ "archived": false } 면 해제) |
POST /tasks/:id/comments | tasks:write | 처리 기록 남기기 |
GET /users | users:read | 사람 이름·이메일 → 사용자 id 찾기 |
GET /projects | projects:read | 프로젝트 목록 |
GET /ext-data/:확장/:모음 · GET …/:문서 | data:read | 확장 저장소(조직 공용) 읽기 |
PUT /ext-data/:확장/:모음/:문서 · DELETE … | data:write | 확장 저장소에 넣기(본문 { "data": … })·지우기 |
POST /notifications/bulk | notify:send | 앱 알림 여러 건 |
curl -X POST "<API 주소>/tasks" \
-H "x-taskflow-api-key: tfk_…" -H "Content-Type: application/json" \
-d '{
"title": "고객 문의 답변",
"description": "주문번호 1234 배송 문의",
"priority": "high",
"assigneeIds": ["user-12"],
"dueDate": "2026-10-25",
"source": { "type": "web-form", "externalId": "form-98231" }
}'const res = await fetch(API + '/tasks?status=in-progress', { headers: { 'x-taskflow-api-key': process.env.TASKFLOW_KEY } });
const { tasks } = await res.json();import os, requests
r = requests.patch(f"{API}/tasks/{task_id}", headers={"x-taskflow-api-key": os.environ["TASKFLOW_KEY"]}, json={"status": "done"})
r.raise_for_status()# 사내 시스템이 매일 밤 재고를 확장 저장소에 넣으면, 확장 화면은 taskflow.data.list('stock') 로 읽는다
curl -X PUT "<API 주소>/ext-data/inventory/stock/A-100" \
-H "x-taskflow-api-key: tfk_…" -H "Content-Type: application/json" \
-d '{ "data": { "name": "노트북", "qty": 12 } }'연동 키로는 비밀 업무가 보이지도 바뀌지도 않고, 업무를 지울 수 없습니다(보관을 쓰세요). createdBy 를 주지 않으면 키를 만든 관리자 이름으로 기록됩니다. 키는 서버·자동화 도구의 비밀 저장소에만 두고 브라우저 코드에 넣지 마세요.
사용 상한
| 대상 | 상한 |
|---|---|
| 확장 화면 → SDK | 10초에 100번 |
| 서버 동작 한 번 | 계산 1.5초 · 전체 20초 · 메모리 32MB · SDK 부르기 60번 · 바깥 통신 10번(각 8초·응답 1MB) · 입출력 256KB · 로그 100줄 |
| 서버 동작 횟수 | 사람마다 1분에 30번 · 확장마다 하루 3,000번 · 예약은 확장마다 3개·15분 이상 간격 |
| 확장 | 화면 코드 800KB · 서버 코드 200KB · 저장소 2만 건(문서 하나 256KB) · 비밀 값 20개 |
| 자동화 · 웹훅 · 연동 키 | 규칙 100개(동작 10개·조건 10개) · 웹훅 30개 · 쓰는 중인 키 20개 |
오류
| 상황 | SDK | REST |
|---|---|---|
| 요청하지 않은 권한 | Error(code: 'PERMISSION_DENIED') | 403 이 연동 키에는 "…" 범위가 없습니다 |
| 볼 수 없거나 없는 업무 | Error 업무를 찾지 못했거나 볼 권한이 없습니다 | 404 |
| 상한 초과 | Error 너무 자주 부르고 있습니다 | 429 |
| 잘못된 키·폐기된 키 | — | 401 |
REST 응답은 모두 JSON 이고 실패하면 { "success": false, "error": "…" } 입니다.
변경 이력
| 2026-10-24 | SDK 판 2 — 기존 기능 바꾸기: 자리 approval-section·project-tab, 확장 전용 표(tables·data.query), 저장 전 규칙(hooks), 원본 대신 쓰기(replaces), 결재 SDK(approval.*·ui.openApproval), TypeScript 형식 정의 |
| 2026-10-23 | SDK 판 1 — 확장 화면·서버 동작·비밀 값·예약 실행·자동화 규칙·웹훅·연동 키(tfk_)·확장 저장소 API |
문의: 조직 관리자 또는 TaskFlow 고객센터.