Zum Inhalt springen
Doku

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.

Aktualisiert am 1. Okt. 2026

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:

  1. Es nimmt die aktuelle Unix-Zeit in Sekunden, zum Beispiel 1790846045, und sendet sie in X-Emailit-Timestamp.
  2. Es bildet den String {timestamp}.{raw body}: den Zeitstempel, einen Punkt und die exakten Bytes des Anfrage-Bodys.
  3. Es berechnet den HMAC-SHA256 dieses Strings mit dem vollständigen Secret, einschließlich whsec_, als Schlüssel.
  4. 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.

server.js
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);

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:

JSON
[{"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.json in 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) oder json.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 wie crypto.timingSafeEqual, hmac.compare_digest, hash_equals, Rack::Utils.secure_compare oder hmac.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.

War diese Seite hilfreich?

Danke für Ihr Feedback.

Danke, wir lesen jede Nachricht.