Webhook 的回應、狀態碼與上限

#兩種回應模式

Webhook 節點的「回應模式 (Response Mode)」決定呼叫端會收到什麼。

#先回 200，再排隊執行

這是預設的模式。網站收到呼叫之後，把執行排進佇列，馬上回應 200 和這次執行的編號：

{ "run_id": "…" }

200 只表示執行已經排好，不表示工作流成功了。之後執行還是可能失敗，請到工作流的執行紀錄查看。

#跑完再回傳資料

網站在這一次 HTTP 請求裡把整個工作流跑完，才回應：

• 工作流裡有「回應 Webhook」節點時，回應由這個節點決定，請看下一段。
• 工作流跑完了，卻沒有「回應 Webhook」節點回應時，呼叫端收到 200 和 {"run_id": "…"}。
• 執行失敗、超過時間上限，或碰到「等待」這類會暫停的節點時，呼叫端收到 500 和 {"message": "工作流執行失敗。", "run_id": "…"}。真正的錯誤不會送給呼叫端，請到工作流的執行紀錄查看。

整個工作流要在 30 秒內跑完。「HTTP 請求」這類要等對方回應的節點，最多只會等到這個時間用完為止。所以這個模式適合很快就能跑完的工作流，而且工作流裡不能有「等待」節點。

#「回應 Webhook」節點

「回應 Webhook」節點在「流程」這一組。它決定呼叫端收到的狀態碼、標頭與內容。

它只在 Webhook 節點設成「跑完再回傳資料」時有用。設成「先回 200，再排隊執行」時，呼叫端在執行開始時就已經收到回應，這個節點的設定不會送出。

• HTTP 狀態碼：100 到 599，預設 200。
• 回應方式 (Respond With)：
  • 「JSON」：送出「回應 Body (JSON)」裡的 JSON。內容不是合法的 JSON 時，這個節點會失敗，訊息是「「回應 Body (JSON)」的內容不是合法的 JSON。」。這個節點的「這個節點失敗時」是預設的「停止工作流」時，呼叫端收到 500。設成「繼續（一般輸出）」或「繼續（錯誤輸出）」時，執行會繼續下去，呼叫端收到的是最後成功執行的那一個「回應 Webhook」節點的回應；一個都沒有時，收到 200 和 {"run_id": "…"}。
  • 「純文字」：送出「回應 Body (純文字)」裡的文字。
  • 「第一筆輸入項目」：把進到這個節點的第一筆資料，當成 JSON 送出。
  • 「全部輸入項目」：把進到這個節點的全部資料，當成一個 JSON 陣列送出。
  • 「不回傳內容」：只送出狀態碼與標頭，沒有內容。
• 回應標頭 (Headers)：要一起送出的標頭。

「純文字」送出時，內容類型是 text/html，不是 text/plain。呼叫端需要純文字時，請在「回應標頭 (Headers)」加上 Content-Type，值填 text/plain; charset=utf-8。「JSON」、「第一筆輸入項目」與「全部輸入項目」送出的都是 JSON。

回應要等整個工作流跑完才送出，不是在這個節點執行的時候。工作流裡有好幾個「回應 Webhook」節點時，由最後執行的那一個決定回應。

請讓回應保持小小的。回應的內容寫成 JSON 後大過大約 256 KB 時，不會送出：呼叫端只會收到一個沒有內容的 200，這個節點設的狀態碼與標頭也都不會送出。大小是照 JSON 算的：英文字母每個算 1 個位元組，中文字（和其他不是英文的字）每個大約算 6 個位元組。所以用中文寫的回應，大約只有一半的大小就會到上限。

這個節點輸出的是回應的內容，不是進來的資料。接在它後面的節點，看到的是回應。

#狀態碼

網站照下面的順序檢查每一次呼叫。第一個沒有通過的檢查，決定呼叫端收到的回應：

所以用錯方法呼叫一個「未啟用」的工作流，收到的是 404，不是 405。「標頭驗證」選的憑證已經被刪掉，或沒有開放給這個工作流時，不論呼叫帶的標頭對不對，收到的都是 500，不是 401。

表裡的 500、401 與 503，工作流都不會執行。其中只有一種會留下執行紀錄：因為每小時的執行次數到了上限而收到 503 時，執行紀錄會有一筆失敗的執行，寫著擋下的原因。

通過這些檢查之後，回應由回應模式決定，請看上面的兩種回應模式。

#JSON 還是 HTML

表裡寫著「網站的錯誤回應」的兩種，是網站自己產生的錯誤。呼叫端要求 JSON 時（例如帶上 Accept: application/json 標頭），收到的是 JSON；不然收到的是一個 HTML 錯誤頁。表裡其他的回應，一定是 JSON。

#上限

#時間上限

設成「跑完再回傳資料」時，整個工作流要在 30 秒內跑完，不然呼叫端會收到 500。

#每分鐘的呼叫次數

每一個 Webhook 節點，一分鐘內最多接受 60 次呼叫。超過的呼叫會收到 429，請等一下再呼叫。每一個 Webhook 節點各算各的。沒有通過其他檢查的呼叫（例如回應 404 的）也會算進去。

#專案的執行上限

Webhook 啟動的執行，和專案其他的工作流執行一起，算在專案的執行上限裡。一個專案一開始的上限是：

• 同時在跑的執行：最多 5 個。只算排隊中與執行中的執行，停在「等待」節點，或停在開著「等待子工作流完成」的「執行子工作流」節點上的不算。
• 每小時的執行次數：最多 500 次。算的是最近一小時內開始的執行，不是整點到整點。
• 每一次執行的時間：最多 900 秒。時間從執行第一次開始時算起，停在「等待」節點，或停在開著「等待子工作流完成」的「執行子工作流」節點上的時間也算在內。網站在兩個節點之間檢查時間：時間到了，執行就在那裡停下來，算是失敗；等待很久的執行，醒來時也會這樣結束。這個檢查有例外，請看下面。

前兩個上限已經滿了的時候，新的呼叫會收到 503，工作流不會執行。

這三個數字是專案一開始的上限。專案可以改成自己的數字。每一個工作流也可以設自己的執行時間上限，可以和專案的一樣或比較短，不能比專案的長。

執行時間上限有幾件事要注意：

• 在佇列裡跑的執行（例如「先回 200，再排隊執行」的 Webhook 啟動的執行），每一段連續執行（從開始，或從暫停醒來，到下一次暫停）最多 900 秒再多一分鐘。這個時間不看專案的數字。
• 一段連續執行跑到這個時間還沒停下來，執行會在節點跑到一半時被中斷。這樣的執行會一直顯示「執行中」，不會變成失敗，也會一直佔著一個同時在跑的名額，直到有人按「停止」把它停掉。
• 因為時間只在兩個節點之間檢查，就算時間上限沒有改過，一個跑很久的節點也可能讓執行這樣被中斷，例如「逾時秒數」設得很長的「HTTP 請求」。
• 專案的執行時間上限設得比 900 秒長，主要只對會暫停的執行有用：停在「等待」節點，或停在開著「等待子工作流完成」的「執行子工作流」節點上，會把執行分成好幾段，每一段各有自己的時間。不會暫停的執行，最多只會多出大約一分鐘。

#在哪裡改專案的上限

1. 在工作流頁打開任何一個工作流。
2. 按上方列的 ⋯（更多）→「工作流設定」。
3. 在這個工作流所在的專案裡，有「管理自動化設定」這項角色權限的人（專案擁有者一定有），會在視窗下方看到「整個專案的設定」。其中的「專案的執行時間上限（秒）」、「同時最多幾個在跑」與「每小時執行次數上限」，就是這三個上限。
4. 改好之後，按「儲存專案設定」。

沒有這項權限的人，看不到「整個專案的設定」。

同一個視窗上方的「執行時間上限（秒）」，是這一個工作流自己的時間上限，一樣只能和專案的一樣或比較短。