Fragen : Wie prüfe ich, dass ein Webhook wirklich von Mailpro kommt (HMAC-Signatur)?

Jeder von Mailpro gesendete Aufruf trägt Header, mit denen Sie ihn authentifizieren können:

X-Mailpro-Signature : t=1758000000,v1=5a72…c8b1
X-Mailpro-Event-Id  : evt_5f2c…
X-Mailpro-Event-Type: email.delivered
X-Mailpro-Attempt   : 1

Berechnung der Signatur

v1 ist der HMAC-SHA256 (hexadezimal, Kleinbuchstaben) der Zeichenkette t + "." + roher Request-Body, berechnet mit dem Secret, das Sie bei der Erstellung des Webhooks erhalten haben. Der Body muss exakt so verwendet werden, wie er empfangen wurde – vor jeder JSON-Dekodierung.

// Node.js
const crypto = require("crypto");
function verify(rawBody, header, secret) {
const t  = header.match(/t=([0-9]+)/)[1];
const v1 = header.match(/v1=([0-9a-f]+)/)[1];
const expected = crypto.createHmac("sha256", secret).update(t + "." + rawBody).digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;   // 5 Minuten
return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Kommen noch keine Ereignisse an? Erstellen und testen Sie Ihren Webhook zuerst und ergänzen Sie dann die Signaturprüfung.

Empfehlungen

• Lehnen Sie jede Anfrage ab, deren Signatur nicht passt oder deren Zeitstempel t älter als wenige Minuten ist (Replay-Schutz).
• Nutzen Sie X-Mailpro-Event-Id, um bereits verarbeitete Ereignisse zu ignorieren: Bei Wiederholungen kann dieselbe Zustellung mehrfach eintreffen.
• Antworten Sie mit 2xx innerhalb von 10 Sekunden und verarbeiten Sie die Nachricht dann asynchron.
• Nach Secret erneuern ist das alte Secret sofort ungültig: Aktualisieren Sie zuerst Ihren Server oder tolerieren Sie eine Minute abgelehnter Signaturen.

Die Webhook-Ziele der Automatisierung (Richtung B) folgen demselben Prinzip – mit dem Header X-Mailpro-Automation-Signature und dem optionalen Signaturschlüssel, den Sie am Ziel festlegen.