一步一步教你設定 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 專案的 webhook，該怎麼做？

可以在訂閱時附加自訂標籤（例如 app|handleProjectA）並依 team 欄位做路由判斷，或是讓每個專案在你的 webhook 網址下擁有各自的子路徑。