Verificare le firme

Chiunque venga a conoscenza dell’URL del tuo endpoint può inviargli richieste. Verifica sempre la firma prima di fidarti di un payload.

Come funziona la firma

Ogni consegna include:

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

La firma è l’HMAC-SHA256 in base64 di "{webhook-id}.{webhook-timestamp}.{raw body}", con chiave i byte del secret: prendi il tuo signing_secret, togli il prefisso whsec_ e decodifica il resto da base64. Rifiuta le richieste il cui timestamp si discosta di più di 5 minuti dal tuo orologio, per impedire i replay.

L’SDK di SpacePost verifica con WebCrypto e restituisce l’evento analizzato. Lancia un’eccezione se la firma o il timestamp non sono validi.

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 });
  }
}

Gli header possono essere un oggetto Headers o un oggetto semplice (ad esempio req.headers di Express). Con Express, monta express.raw({ type: "application/json" }) sulla route del webhook in modo che req.body sia un Buffer.

Con il pacchetto 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,
});

Con svix (o il verificatore del pacchetto resend): usa gli header svix-*, che SpacePost invia ugualmente.

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,
});

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

Senza una libreria:

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,"))

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)
}

Oppure usa la libreria ufficiale: go get github.com/standard-webhooks/standard-webhooks/libraries/go e chiama wh, _ := standardwebhooks.NewWebhook(secret); err := wh.Verify(body, r.Header).

<?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);

Usare il verificatore dell’SDK di Resend

La verifica dei webhook del pacchetto ufficiale resend accetta gli stessi header Standard Webhooks, quindi funziona con il signing_secret di SpacePost.

Ruotare i secret

Il signing_secret è fisso per ogni webhook. Per ruotarlo, crea un nuovo webhook con lo stesso endpoint, fai in modo che il tuo gestore accetti il nuovo secret (provali entrambi durante il passaggio), poi elimina il vecchio webhook.

Test in locale

Invia un’email a delivered@test.spacepost.dev con l’URL di un tunnel registrato come endpoint. Vedi Test.