Webhook 觸發器：讓外部服務直接叫 HA 做事（不用權杖）

charles

上一篇講 REST API，那是你主動去問 HA。
這篇反過來：讓外部直接推東西進 HA。

差別在哪？Webhook 不需要權杖，一個網址就能觸發。
方便，但也因此要小心用。



最小範例

1. alias: 收到 webhook 就開燈
2. triggers:
3.   - trigger: webhook
4.     webhook_id: my-secret-webhook-7f3a9c2e
5.     allowed_methods: [POST]
6.     local_only: true
7. actions:
8.   - action: light.turn_on
9.     target:
10.       entity_id: light.living_room
11. mode: single

複製代碼

觸發它：

1. curl -X POST http://192.168.1.50:8123/api/webhook/my-secret-webhook-7f3a9c2e

複製代碼

就這樣。沒有標頭、沒有權杖。

webhook_id 就是密碼

這點一定要講清楚：任何人知道那串 id，就能觸發你的自動化。

所以：

• 不要用 test、webhook1、door 這種好猜的
  
• 用隨機字串，至少 24 個字元
  
• 產生方式：openssl rand -hex 16 或線上的 UUID 產生器
  
• 每個用途用不同的 id
  

local_only 這個選項很重要

• local_only: true — 只接受內網來的請求（預設，建議保留）
  
• local_only: false — 外網也能打，只有你確定需要才開
  

allowed_methods 也建議明確指定，預設是 POST 和 PUT。
如果你希望用瀏覽器點一下就能觸發（GET），要自己加進去 ——
但那也代表更容易被誤觸發。

帶資料進來

Webhook 可以帶 JSON、表單、或查詢字串，在自動化裡用 trigger.json、
trigger.data、trigger.query 取用。

1. alias: 外部通知轉推播
2. triggers:
3.   - trigger: webhook
4.     webhook_id: notify-bridge-4d81f0aa93
5.     allowed_methods: [POST]
6.     local_only: true
7. actions:
8.   - action: notify.mobile_app_charles
9.     data:
10.       title: "{{ trigger.json.title | default('通知') }}"
11.       message: "{{ trigger.json.message }}"
12. mode: parallel
13. max: 10

複製代碼

呼叫：

1. curl -X POST \
2.   -H "Content-Type: application/json" \
3.   -d '{"title":"伺服器警告","message":"磁碟使用率 92%"}' \
4.   http://192.168.1.50:8123/api/webhook/notify-bridge-4d81f0aa93

複製代碼

實際用途

一：監控系統的告警

Uptime Kuma、Zabbix、Grafana 都支援 webhook 通知。
設定指向 HA，就能讓家裡的燈變紅色、音箱講話，或推播到手機。

我自己是設「NAS 硬碟健康度異常 → 客廳燈閃三下紅色 + 推播」。
這種事光靠 email 會被忽略。

二：iPhone 捷徑

捷徑 App 裡的「取得 URL 內容」，方法選 POST，網址填 webhook。
做成主畫面圖示，一點就執行。比開 HA App 快很多。

三：IFTTT 或其他雲端服務

那些服務不知道你家 HA 的權杖，但可以打一個 webhook。
（要注意這種情況 local_only 得關掉，風險要自己評估，
建議搭配 Nabu Casa 或反向代理，不要直接開通訊埠。）

四：舊裝置的 HTTP 回呼

有些老攝影機、NVR 支援「偵測到動作時呼叫一個網址」。
那個網址填 webhook，就能把不支援 HA 的裝置接進來。

怎麼確認有沒有收到

開發者工具 → 事件 → 監聽事件，輸入：

1. call_service

複製代碼

或者更直接：打開那個自動化的追蹤，觸發一次，看有沒有紀錄。

沒反應的話依序檢查：

• webhook_id 有沒有打錯（大小寫有差）
  
• 是不是從外網打但 local_only 開著
  
• 方法對不對（GET 打到只收 POST 的）
  
• 自動化有沒有啟用
  

安全底線

我的建議是：webhook 只用來觸發「不危險」的動作。

通知、開燈、記錄 —— 可以。
開門鎖、關保全、停止監控 —— 不要。

那些請走需要權杖的 REST API，或至少在自動化裡加條件
（例如「只在有人在家時才執行」）。

---

順帶一提：webhook 的 id 如果外洩了，直接改掉就好，
改完記得同步更新所有呼叫端。