~/教學/WEBHOOK.md

文章 / 做 App

Webhook 是門鈴:叫 Claude Code 三句話接好 GitHub webhook,再用 smee.io 在自己電腦測試

不用每分鐘去問「有新的嗎」:GitHub 一有事就送到你的 App。三句提示詞、GitHub 設定、驗簽章、10 秒規則,和 smee.io 本機測試,全部照官方文件。

很多程式是每分鐘去問一次:「有新的嗎?」像一直跑去開信箱,大部分時候都是空的。Webhook 反過來:你先給 GitHub 一個網址,事情一發生,它就直接把資料送過來。這篇是 Reels 裡 WEBHOOK 那支的完整版:我在自己電腦上跑的那個小收件匣是怎麼做的、叫 Claude Code 的三句話(可以直接複製)、GitHub 後台要填什麼,還有怎麼用 smee.io 在本機測試。GitHub 的部分全部照官方文件,我在 2026 年 11 月 10 日核對過。

01先看結果:GitHub 一有人開 issue,我的 App 馬上收到

一個叫「我的 App・webhook 收件匣」的網頁,最上面一筆是 issues.opened #42 登入頁按了沒反應,延遲 891 ms,簽章打勾
我自己電腦上跑的小 App(真實畫面):事件一進來就出現在最上面,這一筆從送出到收到 891 毫秒。

這個收件匣是一個很小的 Node 程式,只用內建模組,不用裝套件。事件經過 smee.io 轉送進來,App 先檢查簽章,對了才收下,畫面即時更新。整個流程跟真的 GitHub webhook 一樣,只是測試事件是我用 GitHub 的格式自己送的。

  1. Webhook 跟「每分鐘去問一次」差在哪(GitHub 官方文件自己的說法)。
  2. 叫 Claude Code 做的三句話,複製就能用。
  3. GitHub repo 裡要填的 Payload URL 和 Secret。
  4. 用 smee.io 把事件轉到你自己的電腦測試,還有 GitHub 的一鍵重送。

02Webhook 是什麼:不用一直開信箱,等門鈴響就好

Reels 畫面:紙做的門和門鈴,旁邊的瀏覽器開著 GitHub 官方文件 About webhooks,as opposed to polling an API 這句被標紅
Reels 畫面:GitHub 官方文件說,webhook 是事情發生時就把資料送過來,而不是一直去問 API(polling)。

一直去問,叫 polling(輪詢):你的程式每隔一段時間打一次 API,看有沒有新東西。大部分時候都是白跑一趟,問得太勤還可能撞到 API 的次數上限。

Webhook 是門鈴:你在 GitHub 設定一次「哪些事情發生時要通知我、送到哪個網址」,之後每次有人開 issue、push 程式碼、開 PR,GitHub 就會送一個 HTTP 請求到你的網址,裡面是這次事件的資料。你的 App 收到之後,要通知 Discord、重新部署、寫進資料庫,都可以。

03第 1 句:開一個 /webhook 網址,收 GitHub 的事件

在你的專案資料夾打開 Claude Code,把下面這段貼進去。[]裡換成你的情況:

第 1 句(貼給 Claude Code)
幫我用 [Node / Python / 你用的語言] 寫一個小 App(port [3000]):開一個 /webhook 網址,接收 GitHub 的 [issues] 事件;首頁用繁體中文即時列出收到的事件(事件類型、標題、收到的時間)。
GitHub 官方文件 Creating webhooks 的步驟,Payload URL 和 Secret 兩步
GitHub 官方文件:建立 repo webhook 的步驟。
  1. 到你的 repo → Settings → Webhooks → Add webhook。
  2. Payload URL 填你的網址(本機測試時填下面 smee.io 給你的網址)。
  3. Content type 選 application/json,事件內容會直接放在 POST 的 body。
  4. Secret 填一串夠長的隨機字串,等一下第 2 句會用到。
  5. 「Which events」只勾你要的事件,例如 Issues。官方建議只訂需要的,伺服器比較輕鬆。

04第 2 句:用 secret 驗簽章,假的直接擋掉

你的 /webhook 網址是公開的,任何人都可以假裝是 GitHub 送東西過來。GitHub 會用你設定的 secret,替每一次送出的內容算一個簽章,放在 X-Hub-Signature-256 這個 header 裡。你的 App 用同一個 secret 再算一次,對得上才收。

第 2 句(貼給 Claude Code)
用 X-Hub-Signature-256 和我的 secret 驗證每個請求的簽章(HMAC SHA-256,用原始的 body 算,用固定時間的比較),對不上就回 401 擋掉。secret 從環境變數 [WEBHOOK_SECRET] 讀,不要寫死在程式碼裡。
GitHub 官方文件 Validating webhook deliveries,說明簽章放在 X-Hub-Signature-256 header
GitHub 官方文件:簽章怎麼算、放在哪個 header。
我的 App 收件匣的右上角顯示「連線中・已擋掉 1 個假事件」
我的實測(真實畫面):用錯的 secret 簽的假請求被回 401,右上角記下「已擋掉 1 個假事件」。

05第 3 句:收到先回應,再慢慢處理

GitHub 送出之後只等 10 秒。你的伺服器 10 秒內沒有回一個 2XX,GitHub 就會切斷連線,把這次當成失敗。所以要先回「收到了」,真正的工作(寄信、部署、寫資料庫)放到後面做。

第 3 句(貼給 Claude Code)
收到 webhook 先回 202,再在背景慢慢處理,不要讓 GitHub 等超過 10 秒。處理前先看 X-GitHub-Event 和 payload 裡的 action,只處理 [issues.opened],其他的忽略。
GitHub 官方文件 Best practices 的 Respond within 10 seconds 段落
GitHub 官方文件:Respond within 10 seconds。

官方文件的最佳做法裡還有兩條值得一起交代:先看事件類型和 action 再處理(GitHub 會一直加新的事件),以及用 X-GitHub-Delivery 這個 header 認出同一次送出,避免同一筆被處理兩次。

06在自己電腦測試:smee.io 把事件轉到 localhost

GitHub 送不到你電腦上的 localhost,所以官方的測試教學是用 smee.io 當中繼:GitHub 送到 smee.io 的網址,smee 的小程式再轉給你電腦上的 App。我影片裡的實測就是這樣跑的。

  1. 打開 smee.io,按 Start a new channel,複製上面的 Webhook Proxy URL。
  2. 把這個網址填到 GitHub webhook 的 Payload URL。
  3. 在自己電腦把你的 App 跑起來(例如 port 3000)。
  4. 另開一個終端機,裝 smee 的小程式,再開始轉送(指令在下面)。
  5. 去 repo 開一個 issue,看 smee.io 的頁面和你的 App 有沒有收到。
smee 轉送指令(貼進終端機)
npm install --global smee-client
smee --url [你的 smee.io 網址] --path /webhook --port [3000]
smee.io 的 Webhook Deliveries 頁面,列出三筆 issues 事件
我的實測(真實畫面):smee.io 頁面上的三筆事件,兩筆被 App 收下,一筆假的被擋掉。

改完程式想再測一次,不用再開一個 issue:在 repo 的 Settings → Webhooks → 你的 webhook → Recent deliveries,點進某一筆按 Redeliver 就會重送。官方文件寫,可以重送過去 3 天內的事件,要有 repo 的管理權限;GitHub 不會自動幫你重送失敗的那幾筆。

07要注意

  1. secret 不要寫進程式碼、也不要 push 到 GitHub,放在環境變數。網址裡也不要放密碼或 API key(官方文件特別提醒)。
  2. 上線要用 HTTPS 網址;GitHub 預設會檢查 SSL 憑證,官方建議不要關掉。
  3. smee.io 是測試用的中繼,頻道網址知道的人都看得到內容,正式上線要接你自己的伺服器網址。
  4. 同一個事件可能被重送(你按 Redeliver,或你的伺服器沒回應),處理前用 X-GitHub-Delivery 認一下是不是處理過了。
  5. 影片裡的事件是我用 GitHub 格式自己送的測試事件,延遲數字是那一次經過 smee.io 的實測,不代表 GitHub 的速度。

資料來源

延伸閱讀