一步一步教你設定 Quire Webhooks

最後更新：2026 年 7 月 24 日

有沒有想過，如果你的應用程式能自動互相溝通會有多方便？這正是 webhooks 的用途！你可以把它們想像成信差，只要你的 Quire 專案有任何動靜，無論是新建了任務、有人更新了指派，還是將任務標記為完成，它們都會即刻通知你的伺服器。

在這篇指南中，我們會示範如何設定 webhooks，讓你的應用程式與 Quire 保持同步，完全不用你親自動手。

如何開始使用 Quire Webhooks？

步驟 1：建立你的 Quire 應用程式

首先，你需要一個 Quire 應用程式。如果還未建立，可以參考我們的用 Quire API 建立 Quire 應用程式指南，我們會一步步帶你完成。

步驟 2：告訴 Quire 要將更新送到哪裏

接下來，前往 Quire開發者應用程式後台設定你的 webhook 端點。這其實就是你希望 Quire 傳送通知的網址，例如 http://myserver/hookhandler。

你可以把它想像成將你的郵寄地址交給 Quire，讓它知道消息應該送到哪裏。

步驟 3：訂閱更新

最後一個設定步驟，就是告訴 Quire 你想追蹤哪些專案或任務。做法是透過 Quire API，將你的應用程式加入為「追蹤者」：

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

重要提示：請確保你在這一步之前已設定好 webhook 網址。缺少網址的話，將應用程式加入為追蹤者是不會生效的。

當你不再需要接收更新時，只需將應用程式從追蹤者名單中移除就可以，就是這麼簡單！

想了解更多詳情，請參閱我們 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 專案？我們為你準備了兩種靈活做法：

選項 1：使用自訂標籤

訂閱專案更新時，你可以加上自訂標籤：

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;
}

選項 2：使用不同路徑

想將各專案分開處理？可以為每個專案設定專屬路徑：

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 就會即時傳送到你指定的網址，讓你的應用程式毋須輪詢也能保持同步。

如何在 Quire 設定 webhook？

建立一個 Quire 應用程式，在開發者應用程式後台註冊你的端點網址，然後透過 API 將應用程式加入為專案追蹤者。請在訂閱前先設定好網址，否則呼叫會失敗。

如何驗證 webhook 請求真的來自 Quire？

每個酬載都會附上你應用程式的 secret 欄位。將它與你儲存的密鑰比對，不相符的請求一律拒絕。

如果 webhook 觸發時我的伺服器剛好停機，會怎樣？

Quire 會重試三次，分別在 15 分鐘、1 小時及 1 天後。收到酬載後立即回傳 2xx 狀態，就能停止後續重試。

如何在同一台伺服器處理多個 Quire 專案的 webhooks？

你可以在訂閱時附加自訂標籤（例如 app|handleProjectA），再按 team 欄位分流；或者為每個專案在 webhook 網址下設定各自的子路徑。