如何设置 Quire Webhooks:分步指南

最后更新：2026年7月24日

有没有想过,让你的应用程序自动互相"对话"?这正是 webhooks 的作用!把它们想象成信使——只要你关注的 Quire 项目中发生了任何事情,不论是创建了新任务、有人更新了指派,还是把任务标记为完成,它们都会立刻通知你的服务器。

在本指南中,我们会教你如何设置 webhooks,让应用程序与 Quire 保持同步,整个过程无需你动手操心。

如何开始使用 Quire Webhooks?

第一步:创建你的 Quire 应用程序

首先,你需要一个 Quire 应用程序。如果还没设置好,可以参考我们的指南用 Quire API 创建 Quire 应用程序,里面会一步步带你完成。

第二步:告诉 Quire 更新该发到哪里

现在需要在 Quire开发者应用程序 门户中设置你的 webhook 端点。这其实就是你希望 Quire 发送通知的网址,类似 http://myserver/hookhandler 这样的形式。

可以把它理解成把你的通讯地址告诉 Quire,让它知道该把消息送到哪里。

第三步:订阅更新

最后一步设置是告诉 Quire 你想关注哪些项目或任务。做法是通过 Quire API,把你的应用程序添加为"关注者":

curl -H 'Authorization: Bearer {access_token}' -X PUT \
  -d '{"addFollowers":["app"]}' \
  https://quire.io/api/project/projectAOid

重要提示:请确保在这一步之前已经配置好了你的 webhook URL。如果没有配置,将应用程序添加为关注者也不会生效。

当你不再需要接收更新时,只需把应用程序从关注者列表中移除即可,就是这么简单!

想了解更多细节,请查看我们 API 参考文档中的 按 OID 更新项目。

Webhooks 在幕后是如何运作的?

你会收到什么

一切设置完成后,只要你关注的项目中发生了任何事情,Quire 就会开始向你发送通知。这些通知以 POST 请求的形式发送,所有细节都整齐地打包在一个 JSON 数据里:

{
  "type": "notification",
  "secret": "your-app-secret",
  "data": {
    "type": 0, 
    "when": "2019-09-30T08:20:12.000Z",
    "what": {
      "oid": "YxjapXXRCOYxoaiCT4tT3OQm", 
      "id": 101,
      "name": "Brand new start"
    },
    "user": {
      "oid": "1AbDEFed2A5031BEDDweqmde",
      "id": "john.doer",
      "name": "John Doer"
    },
    "message": "<a href=\"https://quire.io/u/john.doer\">John Doer</a> added <a href=\"https://quire.io/w/MyProjects/101\">Brand new start</a>",
    "text": "John Doer added Brand new start",
    "url": "https://quire.io/w/MyProjects/101"
  } 
}

安全第一:验证来源

每个 webhook 都会带上你应用程序的密钥。这是你确认消息确实来自 Quire、而不是有人冒充我们的方式。在处理任何数据之前,请务必先检查这一点!

响应不同的事件

你的项目中会发生各种不同的事情,你可能需要对它们分别处理。下面是一个简单示例,展示如何根据发生的事件类型作出响应:

switch(json["data"]["type"]) {
  case 0:
    // new task added
    log("New task: " + json["data"]["what"]["name"]);
    break;
  case 1:
    // task removed
    log(json["data"]["user"]["name"] + " deleted " + json["data"]["what"]["name"]);
    break;
}

Quire 会发送哪些事件类型?

Quire 可以通知你各种各样的活动,以下是一些最常见的类型:

想看完整列表?欢迎查阅我们的 活动类型文档,了解 Quire 能告诉你的所有信息。

让 Quire 知道你收到了消息

当你的 webhook 收到通知时,只需回传一个成功状态码(200 到 299 之间的任意值)。这会告诉 Quire:"收到了,谢谢!"

如果出了问题,你回传了其他状态码,也不用担心,Quire 会分别在 15 分钟后、1 小时后,最后在 1 天后重新尝试发送通知。

想了解更多细节,请查看我们 API 文档中的 "响应与重试"。

如何管理跨多个项目的 Webhooks?

需要在同一台服务器上处理多个 Quire 项目?我们为你准备了两种灵活的方案:

方案一:使用自定义标签

你可以在订阅项目更新时添加一个自定义标签:

curl -H 'Authorization: Bearer {access_token}' -X PUT \
  -d '{"addFollowers":["app|handleProjectA"]}' \
  https://quire.io/api/project/projectAOid

Quire 会在每条 webhook 通知中都带上这个标签,方便你识别通知来自哪个项目:

{
  "type": "notification",
  "team": "handleProjectA",
  "data": {
    // event details...
  }
}

之后在代码中,你就可以据此对通知进行路由:

switch(json["data"]["type"]) {
  case 0:
    // new task added
    if (json["team"] == "handleProjectA") {
      log("ProjectA has a new task: " + json["data"]["what"]["name"]);
    }
    break;
}

方案二:使用不同的路径

更倾向于把各项目分开处理?可以为每个项目设置独立的路径:

curl -H 'Authorization: Bearer {access_token}' -X PUT \
  -d '{"addFollowers":["app|/projectAUpdate"]}' \
  https://quire.io/api/project/projectAOid

这样一来,Quire 会将通知发送到你主端点下不同的子路径(比如 http://myserver/hookhandler/projectAUpdate),你就可以用各自专属的处理程序来处理每个项目。

通往你的第一个 Webhook 的最快路径是什么?

就是这样!现在你已经知道如何设置 webhooks,让应用程序与 Quire 保持完美同步。想查看完整的技术文档,请参考我们 API 参考文档中的 Webhook 部分。

要为 AI 助手而不是自建服务器搭建集成?可以参考 5 分钟完成 Quire MCP 设置,直接连接 Claude、ChatGPT 或任意 AI 客户端。

祝开发顺利!

常见问题

什么是 Quire webhook?

一种自动化 HTTP 通知,只要你关注的项目中发生任何事情,Quire 就会立刻发送到你指定的 URL——让应用程序无需轮询也能保持同步。

如何在 Quire 中设置 webhook?

创建一个 Quire 应用程序,在开发者应用程序门户中注册你的端点 URL,然后通过 API 将该应用程序添加为项目关注者。请务必在订阅之前先配置好 URL,否则调用会失败。

如何验证某个 webhook 请求确实来自 Quire?

每个负载都会带有你应用程序的 secret 字段——将它与你保存的密钥进行比对,拒绝任何不匹配的请求。

如果 webhook 触发时我的服务器正好宕机,会怎样?

Quire 会重试三次——分别在 15 分钟、1 小时和 1 天后。收到负载后应尽快返回 2xx 状态码,以阻止后续重试。

如何在同一台服务器上处理多个 Quire 项目的 webhooks?

可以在订阅时附加一个自定义标签(例如 app|handleProjectA),再据此对 team 字段进行路由;也可以为每个项目在 webhook URL 下设置独立的子路径。