Webhook 是什麼？接收、驗證、本機測試全攻略

付款結果、訂單狀態變更、LINE 訊息、GitHub push，這些事件無法主動查詢，只有在發生時才知道，要靠 Webhook 接收通知。每秒問一次有沒有新訊息很浪費資源，Webhook 的邏輯反過來，是有訊息時才通知你，即時且省資源。

如果你在做自動化工作流，例如 n8n、Zapier，Webhook 是最常見的觸發器，懂了才能設計完整的自動化流程。而任何人都可以對你的 Webhook URL 發送請求，不驗證簽名，就可能被偽造的事件欺騙，執行錯誤的操作。

Webhook vs API Polling：兩種溝通方式

Webhook 的完整接收流程

1. 建立 Webhook 端點：在後端建立一個 POST 路由，例如 /webhook/stripe，這個 URL 就是你的 Webhook URL。
2. 在對方後台設定：到 Stripe、GitHub、LINE 等服務的後台，填入你的 Webhook URL 和想接收的事件類型。
3. 接收並驗證：對方有事件時會 POST 到你的 URL，要先驗證簽名確認是真的來自對方，再處理資料。
4. 立刻回傳 200：接收到 Webhook 後要盡快回傳 200，告訴對方我收到了，耗時的處理放到背景執行。

from fastapi import FastAPI, Request, HTTPException

app = FastAPI()

@app.post("/webhook/stripe")
async def stripe_webhook(request: Request):
    payload = await request.body()
    sig_header = request.headers.get("stripe-signature")

    # 步驟一：驗證簽名，下一節說明
    event = verify_stripe_signature(payload, sig_header)

    # 步驟二：根據事件類型處理
    if event["type"] == "payment_intent.succeeded":
        handle_payment_success(event["data"]["object"])

    return {"status": "ok"}  # 立刻回傳 200

驗證來源：HMAC Signature

不驗簽名的 Webhook 端點，任何人知道 URL 都能偽造事件。HMAC 簽名讓你能確認請求真的來自你設定的服務：你和對方共享一個 Webhook Secret，對方發送時用這個 Secret 對 Request Body 做 HMAC-SHA256 運算，把結果放在 Header 裡；你收到後用相同的 Secret 對 Body 做相同運算，比對結果，一致就是真的，不一致就是偽造的，拒絕並回傳 400。

import hmac, hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    received = signature.replace("sha256=", "")
    # 用 compare_digest 防止 timing attack
    return hmac.compare_digest(expected, received)

常見 Webhook 場景

本機測試 Webhook：ngrok 和 smee.io

本機的 localhost 外部無法存取，要測試 Webhook 需要把本機暴露到公開網路。