「Webhook」觸發節點讓一個工作流有自己的公開網址。外部系統用 HTTP 呼叫這個網址,工作流就會開始執行。呼叫這個網址不需要登入。
加上 Webhook 觸發
- 在工作流頁打開一個你可以編輯的工作流。
- 從節點清單的「觸發」這一組,加入「Webhook」節點。
- 在節點的設定視窗選「HTTP 方法」。需要時,再設「回應模式 (Response Mode)」、「標頭驗證」與「輸出原始 Body」。
- 按上方列的「儲存」。網址要到這時才會產生。節點設定視窗裡的「儲存」只會把變更放到畫布上,不會存檔。
- 打開上方列的 ⋯(更多)選單。選單裡有一行寫著節點的名稱與方法,例如「Webhook(POST)」。在這一行下面按「複製正式網址」,按鈕會變成「已複製」。
- 把上方列的開關切到「啟用中」。
- 把網址交給外部系統。有設「標頭驗證」時,也要把標頭名稱與標頭值交給對方。
節點的設定視窗不會顯示網址,網址只在 ⋯(更多)選單裡。一個工作流有好幾個 Webhook 節點時,每一個節點都有自己的網址,在選單裡各有自己的一行名稱與「複製正式網址」。只有已經儲存的 Webhook 節點會出現在選單裡。
網址什麼時候有效
- Webhook 節點存進工作流之後,網址會在下一次同步時產生,之後就固定不變。多半是按「儲存」的時候;把工作流切到「啟用中」,或在「工作流設定」按「儲存」時,也會產生。用「建立複本」做出來的工作流,會有自己的新網址。重新命名節點,或是改「HTTP 方法」、「回應模式 (Response Mode)」,網址都不會變。
- 工作流是「未啟用」時,網址一律回應 404。新的工作流一開始都是「未啟用」。只有可以編輯這個工作流的人,看得到「啟用中」/「未啟用」的開關。
- 刪掉 Webhook 節點再加一個新的,會產生新的網址,舊的網址就不能用了。
- 改了節點的設定之後,要按上方列的「儲存」才會生效。
- 每一個網址每分鐘能接受的呼叫有上限,Webhook 啟動的執行也算在專案的執行上限裡,請看上限。
設定
- HTTP 方法:GET、POST、PUT、PATCH、DELETE 或 HEAD,預設是 POST。網址只接受這一個方法,用別的方法呼叫會收到 405。
- 回應模式 (Response Mode):「先回 200,再排隊執行」(預設)或「跑完再回傳資料」。兩種模式各回傳什麼,請看 Webhook 的回應、狀態碼與上限。
- 標頭驗證:選一個種類是「標頭驗證」的憑證,請看下一段。沒有選時,顯示「不使用憑證」。
- 輸出原始 Body:預設關閉,請看下面的呼叫變成的資料。
標頭驗證
沒有設「標頭驗證」時,任何知道網址的人都可以啟動這個工作流,網址就是唯一的鑰匙。
設了之後,呼叫端必須帶上憑證裡的標頭名稱與標頭值。標頭少了或值不對,會收到 401,工作流不會執行。
- 選單只列出開放給這個工作流的「標頭驗證」憑證:它的「權限」分頁要加上這個工作流,請看工作流用得到哪些憑證。一個都沒有時,選單是空的,框下面寫著「還沒有憑證開放給這個工作流。請憑證的擁有者在憑證的「權限」分頁加上它。」,要先請憑證的擁有者在它的「權限」分頁加上這個工作流,才能選。
- 節點選的憑證沒有開放給這個工作流時,每一次呼叫都會收到 500 錯誤,就算標頭是對的也一樣,也不會留下執行紀錄,和憑證被刪掉的時候一樣。私人憑證與別的專案的憑證也一樣:開放給這個工作流就用得到,沒有開放就是 500。
- 選好的憑證被刪掉之後,每一次呼叫都會收到 500 錯誤,不是 401,也不會留下執行紀錄。這時節點上的「標頭驗證」會顯示「不使用憑證」,框下面寫著「這裡找不到選的憑證。」,後面有「清掉」。請選一個新的憑證,再按上方列的「儲存」。按「清掉」再儲存的話,這個 Webhook 就沒有標頭驗證了,任何知道網址的人都可以啟動它。如果沒有別的「標頭驗證」憑證開放給這個工作流,選單會是灰的,要先請憑證的擁有者在它的「權限」分頁加上這個工作流,才能選。
憑證怎麼建立,請看憑證:保存 API 金鑰與密碼。
誰拿得到網址
打得開這個工作流的人,包括只能檢視的人,都可以從 ⋯(更多)選單複製網址。所以重要的工作流,請一定要設「標頭驗證」。
呼叫變成的資料
每一次呼叫,都會變成剛好一筆資料,交給下一個節點。沒有帶任何內容的呼叫,也一樣會有一筆。這筆資料有四個欄位:
| 欄位 | 內容 |
|---|---|
headers |
呼叫帶來的標頭。標頭名稱都是小寫。同一個標頭有好幾個值時,只留第一個。 |
query |
網址上的查詢參數。例如網址後面是 ?id=7,這裡就有 id。 |
body |
呼叫帶來的內容,看「輸出原始 Body」怎麼設。 |
method |
呼叫用的 HTTP 方法,例如 POST。 |
「輸出原始 Body」關閉時(預設),body 是讀好的資料:JSON 或表單的內容,再加上網址上的查詢參數。查詢參數也仍然在 query 裡。要不要當成 JSON 來讀,是看呼叫帶的 Content-Type:送 JSON 時,呼叫端要帶 Content-Type: application/json,不然內容不會被讀進 body。純文字、XML 這些不是 JSON 也不是表單的內容,也不會被讀進 body;要收這種內容,請打開「輸出原始 Body」。
「輸出原始 Body」打開時,body 是呼叫送來的原始文字,沒有經過任何處理。
下一個節點可以用算式讀這筆資料。例如呼叫送來的 JSON 是 {"orderId": 42},而且帶了 Content-Type: application/json,就可以用 {{ $json.body.orderId }} 讀到 42。
用誰的身分執行
Webhook 啟動的執行,是以工作流本身在跑:它用得到的憑證、子工作流與錯誤工作流,只有權限清單上有這個工作流的那些。呼叫端本身沒有使用者身分,請看工作流總覽。
在工作流的執行紀錄裡,Webhook 啟動的執行標示為「Webhook」,觸發者也寫著「Webhook」。
先試試看
想在交給外部系統之前先試試看,可以把工作流切到「啟用中」,自己呼叫「複製正式網址」拿到的網址;或是在 Webhook 節點用「釘選資料」存一份範例資料,再按上方列的「執行」,工作流就會用這份資料跑一次。這個方法只在工作流裡沒有「手動觸發」時才用得到:有「手動觸發」時,「執行」不會從 Webhook 開始。