系列四 02|第一個 Webhook:在自己電腦上開發 LINE Bot
本篇重點
- 了解 Webhook:LINE 平台如何把使用者訊息送到你的程式
- 用 Flask+LINE SDK 寫出第一個 Webhook,完成簽章驗證
- 用 Cloudflare Tunnel 把本機程式公開成 HTTPS 網址
- 在 LINE Developers Console 設定並驗證 Webhook
- 完成「你說什麼,Bot 就回什麼」的鸚鵡回覆
Webhook 是什麼?
上一篇我們用程式「主動」發了一則推播。但 LINE Bot 真正的核心是反過來的方向:使用者傳訊息時,你的程式要能收到。
LINE 的做法叫 Webhook:你先告訴 LINE 一個網址,之後每當有人對官方帳號傳訊息、加好友、按按鈕,LINE 平台就會把這個「事件」用 HTTPS POST 送到那個網址。你的程式收到後處理,再呼叫回覆 API 把答案送回去。
這裡有兩個要解決的問題:
- 怎麼確定請求真的來自 LINE?你的網址是公開的,任何人都能送 POST 過來。答案是「簽章驗證」。
- 家裡的電腦沒有公開的 HTTPS 網址,LINE 平台連不進來。答案是「通道工具」。
簽章驗證:只接受 LINE 送來的請求
LINE 每次送 Webhook 時,都會用你的 Channel secret 對內容計算一組 HMAC-SHA256 簽章,放在 HTTP 標頭 X-Line-Signature。你的程式用同一把 secret 重算一次,兩者相同才代表請求來自 LINE、內容也沒被竄改。
這就是上一篇強調 Channel secret 不能外洩的原因:拿到它的人可以偽造 Webhook,冒充使用者對你的 Bot 下指令。好消息是 LINE 官方 SDK 已經把驗證做好,我們只要呼叫 handler.handle(),驗證失敗它就會拋出例外。
實作一:第一個 Webhook 程式
在上一篇建立的 linebot-bridge 資料夾中(記得先啟用虛擬環境),新增 app.py:
# app.py(第 02 篇):第一個 Webhook,收到文字就原樣回覆
import os
from dotenv import load_dotenv
from flask import Flask, abort, request
from linebot.v3 import WebhookHandler
from linebot.v3.exceptions import InvalidSignatureError
from linebot.v3.messaging import (ApiClient, Configuration, MessagingApi,
ReplyMessageRequest, TextMessage)
from linebot.v3.webhooks import MessageEvent, TextMessageContent
load_dotenv()
app = Flask(__name__)
handler = WebhookHandler(os.getenv("LINE_CHANNEL_SECRET"))
line_config = Configuration(access_token=os.getenv("LINE_CHANNEL_ACCESS_TOKEN"))
@app.route("/", methods=["GET"])
def home():
return "LINE Bot bridge is running."
@app.route("/callback", methods=["POST"])
def callback():
# 1. 取得 LINE 附上的簽章與原始內容
signature = request.headers.get("X-Line-Signature", "")
body = request.get_data(as_text=True)
# 2. 驗證簽章;不是 LINE 送來的請求一律拒絕
try:
handler.handle(body, signature)
except InvalidSignatureError:
print("[Webhook] 簽章驗證失敗,拒絕請求")
abort(400)
return "OK"
@handler.add(MessageEvent, message=TextMessageContent)
def handle_text(event):
user_id = getattr(event.source, "user_id", None)
print(f"[收到] {user_id}:{event.message.text}")
with ApiClient(line_config) as api_client:
MessagingApi(api_client).reply_message(ReplyMessageRequest(
reply_token=event.reply_token,
messages=[TextMessage(text=f"你說:{event.message.text}")],
))
if __name__ == "__main__":
app.run(host="0.0.0.0", port=5000)
程式重點:
| 程式片段 | 作用 |
|---|---|
@app.route("/callback") | LINE 送 Webhook 的網址路徑,稍後要填到後台 |
handler.handle(body, signature) | 驗證簽章,並把事件分派給對應的處理函式 |
@handler.add(MessageEvent, ...) | 宣告「收到文字訊息」時要執行哪個函式 |
event.reply_token | 這次事件專用的回覆憑證,只能用一次 |
reply_message(...) | 用回覆 API 送出訊息(不計入每月額度) |
執行程式:
python app.py
用瀏覽器開啟 http://localhost:5000,看到 LINE Bot bridge is running. 就代表 Flask 正常運作。
實作二:用 Cloudflare Tunnel 借一個 HTTPS 網址
LINE 規定 Webhook 必須是 HTTPS 網址。開發階段最省事的方法是 Cloudflare 的「快速通道」:不用註冊帳號,一行指令就能把本機的 5000 埠公開成一個 https://xxxx.trycloudflare.com 網址。
安裝 cloudflared
# Windows winget install --id Cloudflare.cloudflared # macOS brew install cloudflared # Raspberry Pi / Linux:到 Cloudflare 官方說明頁下載對應版本
開啟通道
另外開一個終端機視窗(原本的 python app.py 要保持執行),輸入:
cloudflared tunnel --url http://localhost:5000
畫面會出現一串訊息,其中有一行類似:
Your quick Tunnel has been created! Visit it at: https://random-words-1234.trycloudflare.com
把這個網址複製下來,用瀏覽器開啟,應該也會看到 LINE Bot bridge is running.,代表外面的世界已經連得到你的電腦了。
注意:快速通道的網址每次都會變
每次重新執行 cloudflared tunnel --url ...,都會拿到一個新的隨機網址,LINE 後台的 Webhook URL 也要跟著改。開發測試沒問題,但要長期使用就不方便,分支 B 會介紹如何取得固定網址。
實作三:在 LINE 後台設定 Webhook
- 進入 LINE Developers Console,選擇你的 Channel,切到 Messaging API 分頁。
- 找到 Webhook settings → Webhook URL,按 Edit,填入「通道網址+
/callback」,例如https://random-words-1234.trycloudflare.com/callback。 - 按 Verify,出現 Success 代表 LINE 平台連得到你的程式,而且簽章驗證通過。
- 把 Use webhook 開關打開。
Verify 時,執行 app.py 的終端機會出現一筆 POST /callback 紀錄,狀態碼 200。
實作四:測試鸚鵡回覆
用手機對官方帳號傳「哈囉」,應該馬上收到「你說:哈囉」。終端機同時會印出:
[收到] U1234abcd...:哈囉
前面那串 U 開頭的字就是傳訊者的 userId,跟上一篇在後台看到的「Your user ID」應該一致。之後第 05 篇做權限控管時,就是靠這個值判斷是不是管理員。
小實驗:冒充 LINE 會怎樣?
在第三個終端機視窗,直接對你的程式送一個沒有簽章的請求:
curl -X POST http://localhost:5000/callback -d "{}"
會得到 400 Bad Request,app.py 的終端機也會印出「簽章驗證失敗,拒絕請求」。這證明了即使有人知道你的網址,也沒辦法冒充 LINE 對 Bot 下指令。
常見問題
Q1:按 Verify 出現 404?
Webhook URL 少了 /callback,或打錯路徑。
Q2:按 Verify 出現 400?
.env 的 LINE_CHANNEL_SECRET 填錯,簽章驗證不通過。注意是 Basic settings 分頁的 Channel secret,不是 access token。
Q3:Verify 逾時或連不上?
確認兩個終端機都還在執行:一個跑 python app.py,一個跑 cloudflared。關掉任何一個,LINE 都會連不到。
Q4:手機收到兩則回覆,一則是我的、一則是制式文字?
官方帳號的「自動回應訊息」沒關掉,請回到第 01 篇的步驟 3。
Q5:關掉電腦後 Bot 就不會回話了?
對,目前程式跑在你的電腦上。這是主線開發階段的正常現象,讀完主線後再從分支 A(雲端)或分支 B(本機常駐)挑一種長期運作的方式。
延伸挑戰
- 修改
handle_text,讓 Bot 回覆時把文字反轉,例如「哈囉」回「囉哈」。 - 在終端機印出事件的完整內容(
print(event)),觀察 LINE 送來的資料結構。 - 試著傳一張貼圖給 Bot,觀察終端機:為什麼沒有反應?(提示:目前只處理
TextMessageContent)
下一篇預告
Bot 會說話了,但還不知道家裡的狀況。下一篇要讓橋接器連上 HiveMQ、訂閱所有裝置的主題並記住最新數據,在 LINE 輸入「狀態」就能查到兩台 ESP32 現在的溫濕度與照度。
系列四:LINE Bot 與裝置互動
📚 系列總整理 |
🗺️ 系列四學習地圖
← 上一篇:01|LINE Bot 架構規劃 |
下一篇:03|橋接 MQTT:查詢裝置狀態 →
留言
張貼留言