TaskView 是一款自托管的项目与任务管理平台，它的 Webhooks（HTTP 事件通知）和 HTTP API 正是自动化的两大基石：当项目中的任务被创建、更新、指派或完成时，TaskView 会实时向你的服务器发送带签名的 HTTP POST 请求，配合 API Token 调用 REST 接口，你就能轻松搭建出属于自己的自定义任务自动化通知系统——对接 Slack、CI/CD 流水线或任何内部工具。

为什么需要 TaskView Webhooks

自建任务通知系统时，你通常希望：任务一完成就自动通知对应团队、任务指派后自动创建 CI 工单、Sprint 结束时自动归档周报。Webhooks 就是 TaskView 为此提供的"事件出口"：

• 按项目订阅，每个项目可配置多个 Webhook
• 支持18 种事件，覆盖任务、工时、Sprint 三大域
• 每次投递附带HMAC-SHA256 签名，可验证请求确实来自 TaskView
• 内置自动重试与投递历史，失败可手动重发

Webhook 快速搭建：7 步完成

1. 打开某个项目
2. 在左侧栏右键项目 → Webhooks
3. 点击Add Webhook
4. 填入接收事件的 URL
5. 勾选要订阅的事件
6. 点击Add保存
7. 立即复制生成的 secret 并妥善保存——它只显示一次

完整的配置说明见官方文档 docs/2.features/7.webhooks.md。

⚠️ URL 必须指向公网地址：127.0.0.1、localhost、10/8、192.168/16等内网地址默认会被拒绝，且 3xx 重定向不会被跟随（重定向会直接记为投递失败）。若接收端（如 n8n、内部机器人）部署在同一内网，可在 API 环境变量中设置WEBHOOKS_ALLOW_PRIVATE_URLS=true，详见 环境变量文档。

18 种事件一览：覆盖任务、工时与 Sprint

所有事件名统一定义在 webhooks.types.ts，事件到 Webhook 的派发逻辑则位于 WebhooksDispatcher.ts。

Payload 格式与签名验证

每次投递都是Content-Type: application/json的 HTTP POST，例如任务更新事件：

{ "event": "task.updated", "timestamp": "2026-03-22T12:00:00.000Z", "task": { "id": 123, "description": "Fix login bug", "statusId": 5, "assignedUsers": [10, 22] }, "changes": { "statusId": 5 }, "initiatorId": 1 }

其中changes字段只出现在task.updated和sprint.updated事件中，且只包含实际变更的字段，非常适合做"只对新变更做响应"的判断。

安全关键点：每个请求都会带X-Webhook-Signature请求头（sha256=...格式的 HMAC-SHA256 签名）。处理 Payload 前务必先校验签名，否则任何知道 URL 的人都可能伪造事件：

const expected = 'sha256=' + crypto .createHmac('sha256', secret) .update(body) // body 必须是原始字符串 .digest('hex')

投递保障：重试、自动禁用与投递历史

TaskView 的 Webhook 投递基于后台任务队列异步执行（见 WebhooksDispatcher.ts），并内置了完整的可靠性机制：

💡 停用后无需删除 Webhook，直接在页面上重新开启即可。

HTTP API 与 API Token：程序化操作任务

Webhooks 负责"事件出"，HTTP API 负责"操作入"。TaskView 提供标准的 REST 接口，配合API Token即可脱离浏览器会话进行程序化访问。

创建 Token：进入Account Settings → API Tokens → Create Token，可设置：

• 权限范围（如仅允许读取和创建任务）
• 项目范围（限定到指定项目）
• 过期时间（过期后返回401 Unauthorized）

Token 以tvk_开头，仅创建时展示一次，数据库只保存 SHA-256 哈希。认证方式为标准 Bearer Token：

curl -H "Authorization: Bearer tvk_a1b2c3d4..." \ https://your-instance.com/module/tasks?goalId=1

常用端点：

Webhook 相关路由的权限校验（登录、项目 Owner、Token 权限三重中间件）可参考 WebhooksRoutes.ts。

更省事的方案——官方 SDK：仓库内置taskview-api客户端包（taskview-packages/taskview-api/），安装后即可类型安全地调用全部接口：

import axios from 'axios' import { TvApi } from 'taskview-api' const api = new TvApi(axios.create({ baseURL: 'https://your-instance.com', headers: { Authorization: 'Bearer tvk_your_token_here' }, })) const tasks = await api.tasks.fetch({ goalId: 1 }) // 拉取任务 const newTask = await api.tasks.createTask({ // 创建任务 goalId: 1, description: 'Task created via API', })

API Token 的完整说明见 docs/2.features/8.api-tokens.md。

典型自动化场景：从事件到通知

把 Webhook 与 API 组合起来，几类常见玩法几乎零成本实现：

📣 场景一：任务变更推送到 IM接收task.created/task.assigneesChanged事件 → 校验签名 → 调用你的 Slack/企业微信机器人接口转发。若想免去自己维护机器人，TaskView 也内置了 Telegram 与 Slack 消息集成（个人私聊 + 项目群频道两级），配置指南见 docs/3.integrations/3.messaging.md。

🔄 场景二：Sprint 生命周期驱动 CI/CD订阅sprint.activated触发构建流水线、sprint.completed生成周报——Sprint 生命周期事件会携带完整 Sprint 对象（名称、日期、goalAchieved等），无需二次查询。

🤖 场景三：双向同步闭环Webhook 收到task.updated且changes中含statusId→ 通过 HTTP API 的GET /module/tasks获取任务详情 → 同步到外部系统；反向则用PATCH /module/tasks回写状态，形成闭环。

⏱ 场景四：工时统计报表订阅全部time-entry.*事件，把开始/停止计时实时汇入你的工时看板或计费系统。

⚠️ 本地测试提示：由于回环地址默认被拒绝，本地调试可启动 API 时设置WEBHOOKS_ALLOW_PRIVATE_URLS=true，或用 ngrok、Cloudflare Tunnel 等隧道暴露接收端。

总结

TaskView 的 Webhooks 与 HTTP API 覆盖了自托管任务管理自动化的完整链路：Webhook 事件出站（18 种事件 + 签名验证 + 自动重试）、API Token 认证 + REST 接口出站入站、再叠加官方taskview-apiSDK，足以支撑 IM 通知、CI/CD 联动、双向同步等绝大多数自定义任务自动化通知系统。配合自托管的部署方式，数据与事件流都完全掌握在自己手中。