安全與 HMAC 簽名

Savebase 傳送的每個 Webhook 請求都使用 HMAC-SHA256 簽名，讓你確認它確實來自 Savebase，且傳輸途中未被篡改。處理 Webhook 事件前，請始終驗證該簽名。

簽名如何工作

Savebase 使用 Webhook 的以下資訊，對原始請求體執行 HMAC-SHA256 來計算簽名 簽名金鑰 作為金鑰。結果在以下欄位中傳送 X-Savebase-Signature 請求頭，形式為 sha256=<hex-digest>.

使用原始請求體

始終對以下內容計算 HMAC： 原始且未經修改的請求體位元組 — 而非重新序列化的 JSON 物件。解析並重新序列化 JSON 可能改變空白和鍵順序，導致簽名驗證失敗。

請求頭	值格式
`X-Savebase-Signature`	`sha256=abcdef0123...`
`X-Savebase-Event`	`post.saved`
`User-Agent`	`Savebase-Webhook/1.0`

Node.js / Express

bash

const crypto = require('crypto');

function verifySignature(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'utf8'),
    Buffer.from(signatureHeader, 'utf8')
  );
}

app.post(
  '/savebase-webhook',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const sig = req.headers['x-savebase-signature'];
    if (!sig || !verifySignature(req.body, sig, process.env.SAVEBASE_WEBHOOK_SECRET)) {
      return res.status(401).send('Invalid signature');
    }
    const event = JSON.parse(req.body);
    console.log('Event:', event.event, event.data.id);
    res.sendStatus(200);
  }
);

Python / Flask

bash

import hmac, hashlib, os
from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_SECRET = os.environ['SAVEBASE_WEBHOOK_SECRET']

@app.route('/savebase-webhook', methods=['POST'])
def handle_webhook():
    sig_header = request.headers.get('X-Savebase-Signature', '')
    raw_body = request.get_data()

    expected = 'sha256=' + hmac.new(
        WEBHOOK_SECRET.encode('utf-8'),
        raw_body,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, sig_header):
        abort(401)

    payload = request.get_json()
    print('Received event:', payload['event'])
    return '', 200

PHP

bash

<?php
$secret  = getenv('SAVEBASE_WEBHOOK_SECRET');
$rawBody = file_get_contents('php://input');
$sigHeader = $_SERVER['HTTP_X_SAVEBASE_SIGNATURE'] ?? '';
$expected  = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);

if (!hash_equals($expected, $sigHeader)) {
    http_response_code(401);
    exit('Invalid signature');
}

$event = json_decode($rawBody, true);
error_log('Received: ' . $event['event']);
http_response_code(200);

安全最佳實踐

迅速響應。 返回一個 200 OK 須在 10 秒內完成。Savebase 在 10 秒後超時並將投遞標記為失敗。耗時工作請交由背景任務處理。
切勿將簽名金鑰寫入日誌。 像密碼一樣保護它，並在以下位置輪換 Settings → Webhooks 如果認為它已洩露。
僅使用 HTTPS。 Savebase 拒絕純 HTTP 端點。
使用恆定時間比較。 始終使用 crypto.timingSafeEqual （Node）、 hmac.compare_digest （Python），或 hash_equals （PHP），絕不能使用明文 ===.
自行處理失敗情況。 Savebase 記錄投遞結果，但目前實現不會自動重試或重放失敗請求。

上一步

概覽與設定

下一步

投遞日誌與測試