# Webhook

Source: https://openflow.run/zh-tw/docs/nodes/webhook/
Language: zh-TW
Product version: 0.1.0-beta.77

透過 HTTP 請求啟動工作流程，並選擇回應的內容和時機。

Webhook 將收到的 HTTP 請求作為一次執行的入口。需要將工作流程發布到能夠對外提供 Webhook 地址的部署環境。

## 宣告請求

選擇 HTTP 方法，並宣告請求本文欄位。公開編排介面透過 `config.body` 接收按名稱組織的欄位定義。

```json
{
  "op": "node.add", "as": "webhook", "type": "webhook", "name": "Receive a ticket",
  "config": {
    "method": "POST",
    "body": { "message": { "schema": { "type": "string" }, "nullable": false } }
  }
}
```

請求資料透過觸發器宣告的輸出提供。讀取請求本文欄位時，從 `body` 輸出中按直接屬性名選擇。請求不會自動把值綁定到任意下游輸入。

## 選擇回應模式

*   **立即回應**：省略 `options.responseBody`，使用已設定的即時回應。
*   **工作流程輸出**：選擇 `kind: "workflow-outputs"`，等待整次執行成功後回傳全部工作流程輸出或其中一個欄位。
*   **回應節點**：選擇 `kind: "webhook-response"`，指定一個可達節點，在它第一次成功完成時回傳回應。

POST Webhook 將宣告的 message 傳給程式碼節點；Webhook 回應節點回傳確認訊息，後續任務仍可繼續。

**輸入**
POST 請求本文：{"message":"Please check my order"}

**預期結果**
HTTP 202，文字為 "Received: Please check my order"，並包含 X-Workflow: ticket-intake。

**執行前準備**
將工作流程發布到對外提供 Webhook 地址的部署環境。

[下載工作流程](https://openflow.run/docs/examples/webhook-response.openflow.json)

## 動態回應限制

動態回應超時範圍為 1,000–60,000 毫秒，預設為 30,000 毫秒，排隊和等待時間也計入其中。HTTP 超時不會取消已經接收的執行。

工作流程輸出模式中，字串按文字回傳，其他 JSON 值按 JSON 回傳。選定輸出缺失或執行未成功時會回傳錯誤。狀態碼和回應標頭也可按文件規定的約束，從工作流程輸出中選擇。

切換模式時，應明確清除相應欄位。固定回應文字、狀態碼和回應標頭即使目前未生效，也可能仍保留設定。清除一個巢狀欄位，不等於清除了其他回應策略。

CORS、回應標頭限制、請求限制和對外地址設定，均以部署端規則為準。提前確認請求的用法見 [Webhook 回應](https://openflow.run/zh-tw/docs/nodes/webhook-response/index.md)。

## 資料來源

*   [docs/authoring/node-authoring.md](https://github.com/oomol-lab/open-flow/blob/e25a738d170322734572a0b8a1323cb00b9d355a/docs/authoring/node-authoring.md#webhook-http-responses)
*   [docs/control/contracts/control-api.md](https://github.com/oomol-lab/open-flow/blob/e25a738d170322734572a0b8a1323cb00b9d355a/docs/control/contracts/control-api.md#trigger-configuration-and-outputs)
*   [packages/open-flow/src/workbench/browser/runtime/editor/addNodeOptions.ts](https://github.com/oomol-lab/open-flow/blob/e25a738d170322734572a0b8a1323cb00b9d355a/packages/open-flow/src/workbench/browser/runtime/editor/addNodeOptions.ts)