署名の検証

エンドポイントの URL を知った人は誰でも、そこに POST できます。ペイロードを信頼する前に、必ず署名を検証してください。

署名の仕組み

各配信には、次の内容が付きます。

webhook-id:        0192e1c4-0000-7000-8000-0000000000cc
webhook-timestamp: 1761228131
webhook-signature: v1,K5oZfzN0mYI+Hx3Yb0v8j3H5kq2tqZ2dA8s0r6sF9Vw=

署名は、"{webhook-id}.{webhook-timestamp}.{raw body}" の base64 形式の HMAC-SHA256 で、シークレットのバイト列を鍵にします。signing_secret から whsec_ プレフィックスを取り除き、残りを base64 デコードしてください。リプレイ攻撃を防ぐため、タイムスタンプが手元の時計から 5 分以上ずれているリクエストは拒否します。

注意

受信したとおりの生のリクエストボディに対して検証してください。フレームワークが先に JSON をパースして再シリアライズすると、署名が一致しなくなります。

Node.js

SpacePost の SDK は WebCrypto で検証し、パース済みのイベントを返します。署名またはタイムスタンプが不正な場合は例外をスローします。

webhook-handler.ts

import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

/** Works as a Bun, Deno, Cloudflare Workers or Next.js route handler. */
export async function POST(request: Request): Promise<Response> {
  const payload = await request.text(); // the RAW body: do not parse it first

  try {
    const event = await spacepost.webhooks.verify({
      payload,
      headers: request.headers,
      secret: process.env.SPACEPOST_WEBHOOK_SECRET!,
    });

    switch (event.type) {
      case "email.bounced":
      case "email.complained":
        console.warn("Stop mailing", event.data.to);
        break;
      case "email.delivered":
        console.log("Delivered", event.data.email_id);
        break;
    }
    return new Response("ok");
  } catch {
    return new Response("invalid signature", { status: 400 });
  }
}

ヘッダーには、Headers オブジェクトまたはプレーンなオブジェクト（たとえば Express の req.headers）を渡せます。Express では、req.body が Buffer になるように、Webhook のルートに express.raw({ type: "application/json" }) をマウントしてください。

standardwebhooks パッケージを使う場合:

import { Webhook } from "standardwebhooks";

const wh = new Webhook(process.env.SPACEPOST_WEBHOOK_SECRET!); // "whsec_..." is accepted
const event = wh.verify(rawBody, {
  "webhook-id": req.headers["webhook-id"] as string,
  "webhook-timestamp": req.headers["webhook-timestamp"] as string,
  "webhook-signature": req.headers["webhook-signature"] as string,
});

svix を使う場合（または resend パッケージの検証機能）: SpacePost が併せて送信している svix-* ヘッダーを使います。

import { Webhook } from "svix";

const wh = new Webhook(process.env.SPACEPOST_WEBHOOK_SECRET!);
const event = wh.verify(rawBody, {
  "svix-id": req.headers["svix-id"] as string,
  "svix-timestamp": req.headers["svix-timestamp"] as string,
  "svix-signature": req.headers["svix-signature"] as string,
});

Python

pip install standardwebhooks

import os
from flask import Flask, request
from standardwebhooks.webhooks import Webhook, WebhookVerificationError

app = Flask(__name__)
wh = Webhook(os.environ["SPACEPOST_WEBHOOK_SECRET"])  # "whsec_..." is accepted

@app.post("/webhooks/spacepost")
def spacepost_webhook():
    try:
        event = wh.verify(request.get_data(as_text=True), dict(request.headers))
    except WebhookVerificationError:
        return "invalid signature", 400
    print(event["type"], event["data"]["email_id"])
    return "", 200

ライブラリを使わない場合:

import base64, hashlib, hmac, time

def verify(secret: str, headers: dict, body: bytes, tolerance: int = 300) -> bool:
    msg_id = headers["webhook-id"]
    ts = headers["webhook-timestamp"]
    if abs(time.time() - int(ts)) > tolerance:
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{ts}.".encode() + body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
    return any(hmac.compare_digest(s.split(",", 1)[1], expected)
               for s in headers["webhook-signature"].split() if s.startswith("v1,"))

Go

package main

import (
  "crypto/hmac"
  "crypto/sha256"
  "encoding/base64"
  "fmt"
  "io"
  "math"
  "net/http"
  "os"
  "strconv"
  "strings"
  "time"
)

func verify(secret string, h http.Header, body []byte) bool {
  id := h.Get("webhook-id")
  ts := h.Get("webhook-timestamp")
  n, err := strconv.ParseInt(ts, 10, 64)
  if err != nil || math.Abs(float64(time.Now().Unix()-n)) > 300 {
    return false
  }
  key, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_"))
  if err != nil {
    return false
  }
  mac := hmac.New(sha256.New, key)
  mac.Write([]byte(id + "." + ts + "."))
  mac.Write(body)
  expected := base64.StdEncoding.EncodeToString(mac.Sum(nil))
  for _, s := range strings.Fields(h.Get("webhook-signature")) {
    if v, ok := strings.CutPrefix(s, "v1,"); ok && hmac.Equal([]byte(v), []byte(expected)) {
      return true
    }
  }
  return false
}

func main() {
  http.HandleFunc("/webhooks/spacepost", func(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)
    if !verify(os.Getenv("SPACEPOST_WEBHOOK_SECRET"), r.Header, body) {
      http.Error(w, "invalid signature", http.StatusBadRequest)
      return
    }
    fmt.Println("event:", string(body))
    w.WriteHeader(http.StatusOK)
  })
  http.ListenAndServe(":8080", nil)
}

公式ライブラリを使うこともできます。go get github.com/standard-webhooks/standard-webhooks/libraries/go を実行し、wh, _ := standardwebhooks.NewWebhook(secret); err := wh.Verify(body, r.Header) を呼び出します。

PHP

<?php
function verify_spacepost_webhook(string $secret, array $headers, string $body, int $tolerance = 300): bool {
    $headers = array_change_key_case($headers, CASE_LOWER);
    $id = $headers['webhook-id'] ?? '';
    $ts = $headers['webhook-timestamp'] ?? '';
    if (!ctype_digit($ts) || abs(time() - (int) $ts) > $tolerance) {
        return false;
    }
    $key = base64_decode(preg_replace('/^whsec_/', '', $secret));
    $expected = base64_encode(hash_hmac('sha256', "$id.$ts.$body", $key, true));
    foreach (explode(' ', $headers['webhook-signature'] ?? '') as $sig) {
        if (str_starts_with($sig, 'v1,') && hash_equals($expected, substr($sig, 3))) {
            return true;
        }
    }
    return false;
}

$body = file_get_contents('php://input');
if (!verify_spacepost_webhook(getenv('SPACEPOST_WEBHOOK_SECRET'), getallheaders(), $body)) {
    http_response_code(400);
    exit('invalid signature');
}
$event = json_decode($body, true);
error_log($event['type'] . ' ' . $event['data']['email_id']);
http_response_code(200);

Resend SDK の検証機能を使う

公式の resend パッケージの Webhook 検証は、同じ Standard Webhooks ヘッダーを受け取るため、SpacePost の signing_secret でそのまま動作します。

シークレットをローテーションする

signing_secret は Webhook ごとに固定です。ローテーションするには、同じエンドポイントで新しい Webhook を作成し、ハンドラーが新しいシークレットを受け付けるように切り替え（切り替え期間中は両方を試します）、古い Webhook を削除します。

ローカルでテストする

トンネルの URL をエンドポイントとして登録し、delivered@test.spacepost.dev にメールを送信します。テストをご覧ください。