Anleitung
Webhook-Signaturen verifizieren
Prüfen Sie, ob Webhook-Anfragen von Emailit stammen, indem Sie die HMAC-SHA256-Signatur und den Zeitstempel verifizieren, mit Code für Node.js, Python, PHP, Ruby, Go und Laravel.
Wer Ihre Webhook-URL kennt, kann Anfragen an sie senden. Jede Anfrage von Emailit ist mit dem Secret Ihres Webhooks signiert; die Verifizierung der Signatur belegt daher, dass die Anfrage von Emailit stammt und unterwegs nicht verändert wurde. Die Prüfung des Zeitstempels verhindert außerdem, dass alte Anfragen erneut eingespielt werden. Tun Sie beides, bevor Sie auf ein Event reagieren.
So funktioniert die Signatur
Jeder Webhook hat sein eigenes Secret: whsec_, gefolgt von 64 Hexadezimalzeichen. Sie sehen es einmal, wenn Sie den Webhook erstellen oder das Secret zurücksetzen, und Webhook abrufen gibt es zurück.
Für jede Anfrage geht Emailit so vor:
- Es nimmt die aktuelle Unix-Zeit in Sekunden, zum Beispiel
1790846045, und sendet sie inX-Emailit-Timestamp. - Es bildet den String
{timestamp}.{raw body}: den Zeitstempel, einen Punkt und die exakten Bytes des Anfrage-Bodys. - Es berechnet den HMAC-SHA256 dieses Strings mit dem vollständigen Secret, einschließlich
whsec_, als Schlüssel. - Es sendet das Ergebnis, hexadezimal kodiert in Kleinbuchstaben, in
X-Emailit-Signature.
Zur Verifizierung wiederholt Ihr Endpunkt die Schritte 2 und 3 mit dem unveränderten Body, den er erhalten hat, und vergleicht sein Ergebnis per Vergleich in konstanter Zeit mit dem Header. Anschließend prüft er, ob der Zeitstempel aktuell ist. Wir empfehlen eine Toleranz von 5 Minuten (300 Sekunden). Jede Wiederholung wird mit einem neuen Zeitstempel erneut signiert, daher lehnt ein Zeitfenster von 5 Minuten keine Wiederholungen ab.
Anfragen verifizieren
Jedes Beispiel liest den unveränderten Body, lehnt Anfragen mit fehlender, veralteter oder falscher Signatur mit 401 ab und parst erst dann das JSON-Array.
import crypto from 'node:crypto';
import express from 'express';
const app = express();
const SECRET = process.env.EMAILIT_WEBHOOK_SECRET; // full value, including whsec_
const TOLERANCE_SECONDS = 300;
export function verifyEmailitSignature(rawBody, signature, timestamp) {
if (!signature || !timestamp) return false;
const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
if (!(age <= TOLERANCE_SECONDS)) return false; // also rejects non-numeric timestamps
const expected = crypto
.createHmac('sha256', SECRET)
.update(`${timestamp}.`)
.update(rawBody) // a Buffer with the exact bytes received
.digest('hex');
const a = Buffer.from(expected);
const b = Buffer.from(signature);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
// express.raw() keeps the body as a Buffer. Don't run express.json() on this route.
app.post('/webhooks/emailit', express.raw({ type: 'application/json' }), (req, res) => {
const valid = verifyEmailitSignature(
req.body,
req.get('X-Emailit-Signature'),
req.get('X-Emailit-Timestamp'),
);
if (!valid) return res.status(401).send('Invalid signature');
const events = JSON.parse(req.body.toString('utf8'));
// Queue the events for processing, then acknowledge.
res.sendStatus(204);
});
app.listen(3000);import hashlib
import hmac
import json
import os
import time
from flask import Flask, abort, request
app = Flask(__name__)
SECRET = os.environ["EMAILIT_WEBHOOK_SECRET"].encode() # full value, including whsec_
TOLERANCE_SECONDS = 300
def verify_emailit_signature(raw_body: bytes, signature: str | None, timestamp: str | None) -> bool:
if not signature or not timestamp:
return False
try:
age = abs(time.time() - int(timestamp))
except ValueError:
return False
if age > TOLERANCE_SECONDS:
return False
expected = hmac.new(SECRET, timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)
@app.post("/webhooks/emailit")
def emailit_webhook():
raw_body = request.get_data() # raw bytes; don't use request.json first
if not verify_emailit_signature(
raw_body,
request.headers.get("X-Emailit-Signature"),
request.headers.get("X-Emailit-Timestamp"),
):
abort(401)
events = json.loads(raw_body)
# Queue the events for processing, then acknowledge.
return "", 204<?php
const TOLERANCE_SECONDS = 300;
function verifyEmailitSignature(string $rawBody, string $signature, string $timestamp, string $secret): bool
{
if ($signature === '' || !ctype_digit($timestamp)) {
return false;
}
if (abs(time() - (int) $timestamp) > TOLERANCE_SECONDS) {
return false;
}
$expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
return hash_equals($expected, $signature);
}
$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_EMAILIT_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_EMAILIT_TIMESTAMP'] ?? '';
$secret = (string) getenv('EMAILIT_WEBHOOK_SECRET'); // full value, including whsec_
if (!verifyEmailitSignature($rawBody, $signature, $timestamp, $secret)) {
http_response_code(401);
exit('Invalid signature');
}
$events = json_decode($rawBody, true);
// Queue the events for processing, then acknowledge.
http_response_code(204);require 'sinatra'
require 'openssl'
require 'json'
require 'rack/utils'
SECRET = ENV.fetch('EMAILIT_WEBHOOK_SECRET') # full value, including whsec_
TOLERANCE_SECONDS = 300
def verify_emailit_signature(raw_body, signature, timestamp)
return false if signature.to_s.empty? || timestamp.to_s !~ /\A\d+\z/
return false if (Time.now.to_i - timestamp.to_i).abs > TOLERANCE_SECONDS
expected = OpenSSL::HMAC.hexdigest('SHA256', SECRET, "#{timestamp}.#{raw_body}")
Rack::Utils.secure_compare(expected, signature)
end
post '/webhooks/emailit' do
raw_body = request.body.read # in Rails, use request.raw_post
valid = verify_emailit_signature(
raw_body,
request.env['HTTP_X_EMAILIT_SIGNATURE'],
request.env['HTTP_X_EMAILIT_TIMESTAMP']
)
halt 401, 'Invalid signature' unless valid
events = JSON.parse(raw_body)
# Queue the events for processing, then acknowledge.
status 204
endpackage main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"io"
"net/http"
"os"
"strconv"
"time"
)
const toleranceSeconds = 300
func verifyEmailitSignature(rawBody []byte, signature, timestamp, secret string) bool {
ts, err := strconv.ParseInt(timestamp, 10, 64)
if err != nil || signature == "" {
return false
}
age := time.Now().Unix() - ts
if age > toleranceSeconds || age < -toleranceSeconds {
return false
}
mac := hmac.New(sha256.New, []byte(secret))
mac.Write([]byte(timestamp + "."))
mac.Write(rawBody)
expected := hex.EncodeToString(mac.Sum(nil))
return hmac.Equal([]byte(expected), []byte(signature))
}
type Event struct {
EventID string `json:"event_id"`
Type string `json:"type"`
Data json.RawMessage `json:"data"`
}
func emailitWebhook(w http.ResponseWriter, r *http.Request) {
rawBody, err := io.ReadAll(r.Body)
if err != nil {
http.Error(w, "cannot read body", http.StatusBadRequest)
return
}
secret := os.Getenv("EMAILIT_WEBHOOK_SECRET") // full value, including whsec_
if !verifyEmailitSignature(rawBody, r.Header.Get("X-Emailit-Signature"), r.Header.Get("X-Emailit-Timestamp"), secret) {
http.Error(w, "invalid signature", http.StatusUnauthorized)
return
}
var events []Event
if err := json.Unmarshal(rawBody, &events); err != nil {
http.Error(w, "invalid JSON", http.StatusBadRequest)
return
}
// Queue the events for processing, then acknowledge.
w.WriteHeader(http.StatusNoContent)
}
func main() {
http.HandleFunc("/webhooks/emailit", emailitWebhook)
http.ListenAndServe(":8080", nil)
}<?php
// config/services.php: 'emailit' => ['webhook_secret' => env('EMAILIT_WEBHOOK_SECRET')],
// routes/api.php: Route::post('/webhooks/emailit', EmailitWebhookController::class);
namespace App\Http\Controllers;
use App\Jobs\ProcessEmailitEvent;
use Illuminate\Http\Request;
use Illuminate\Http\Response;
class EmailitWebhookController extends Controller
{
private const TOLERANCE_SECONDS = 300;
public function __invoke(Request $request): Response
{
$rawBody = $request->getContent();
$signature = (string) $request->header('X-Emailit-Signature', '');
$timestamp = (string) $request->header('X-Emailit-Timestamp', '');
$secret = (string) config('services.emailit.webhook_secret'); // full value, including whsec_
$fresh = ctype_digit($timestamp)
&& abs(time() - (int) $timestamp) <= self::TOLERANCE_SECONDS;
$expected = hash_hmac('sha256', $timestamp.'.'.$rawBody, $secret);
abort_unless($fresh && hash_equals($expected, $signature), 401, 'Invalid signature');
foreach (json_decode($rawBody, true) as $event) {
ProcessEmailitEvent::dispatch($event); // a queued job
}
return response()->noContent();
}
}In Laravel werden Routen in routes/api.php nicht auf CSRF-Tokens geprüft und erhalten das Präfix /api, daher lautet die URL oben https://acme.com/api/webhooks/emailit. Wenn Sie die Route in routes/web.php registrieren, nehmen Sie den Pfad von der CSRF-Prüfung aus, sonst lehnt Laravel die Anfragen von Emailit mit 419 ab.
Verifizierung testen
Prüfen Sie Ihre Funktion mit diesem bekannten Beispiel, bevor Sie sie bereitstellen. Rufen Sie den HMAC-Teil direkt auf, weil der Zeitstempel in der Vergangenheit liegt und die 5-Minuten-Prüfung nicht besteht.
| Eingabe | Wert |
|---|---|
| Secret | whsec_4f2a9c1e7b3d5a8f0e6c2b9d4a7f1e3c5b8d0a2f6e9c3b7d1a5f8e2c4b6d9a0f |
| Zeitstempel | 1790846045 |
| Erwartete Signatur | 7242b580f77ec488f8ac21b57f092e3db61a431694f13074c7b4c85a4dd04be3 |
Unveränderter Body, genau wie gezeigt, ohne abschließenden Zeilenumbruch:
[{"event_id":"evt_2xGk7Nq1VbD5sR8tLmW3eYhC6aP","type":"email.delivered"}]Prüfen Sie dann mit Send test am Webhook, ob Ihr bereitgestellter Endpunkt eine echte signierte Anfrage annimmt. Siehe Webhook einrichten.
Häufige Fehler
- Parsen vor dem Verifizieren. Frameworks, die JSON automatisch parsen (
express.json(),request.jsonin Flask, Rails-Params), liefern Ihnen ein Objekt, nicht die Bytes, die Emailit signiert hat. Lesen Sie auf der Webhook-Route den unveränderten Body. - Erneutes Serialisieren des JSON.
JSON.stringify(req.body)oderjson.dumps(data)erzeugt andere Leerzeichen, eine andere Schlüsselreihenfolge oder ein anderes Escaping, sodass der HMAC nicht übereinstimmt. Hashen Sie den Body immer genau so, wie Sie ihn erhalten haben. - Verändern des Secrets. Verwenden Sie den gesamten Wert, einschließlich
whsec_, als Klartext. Entfernen Sie das Präfix nicht und dekodieren Sie den Wert weder hexadezimal noch per Base64. - Signieren des falschen Strings. Die Eingabe ist der Zeitstempel, ein Punkt, dann der Body. Nur den Body zu signieren oder ein anderes Trennzeichen zu verwenden, schlägt fehl.
- Vergleich mit
==. Verwenden Sie eine Funktion mit konstanter Laufzeit wiecrypto.timingSafeEqual,hmac.compare_digest,hash_equals,Rack::Utils.secure_compareoderhmac.Equal. - Falsche Serveruhr. Weicht die Uhr Ihres Servers ab, fallen gültige Anfragen aus der Toleranz. Halten Sie sie per NTP synchron.
- Altes oder falsches Secret. Nach Reset funktioniert das alte Secret sofort nicht mehr, auch nicht für Wiederholungen. Jeder Webhook hat sein eigenes Secret, daher können sich zwei Endpunkte keines teilen.
- Middleware, die den Body umschreibt. Proxys, API-Gateways oder eine Dekomprimierung des Bodys, die die Bytes verändern, bevor Ihr Code sie sieht, machen die Signatur ungültig. Verifizieren Sie so nah an der unveränderten Anfrage wie möglich.
Anfragen, deren Verifizierung fehlschlägt, erhalten von Ihrem Endpunkt ein 401 und werden wie jeder andere Fehlschlag wiederholt; wenn Sie ein falsch konfiguriertes Secret innerhalb weniger Stunden korrigieren, geht also nichts verloren.