Webhooks
Ereignisse wie Abmeldungen, Bounces oder neue Leads in Echtzeit an Ihr System senden, mit HMAC-Signatur und automatischen Wiederholungen.
Webhooks informieren Ihre anderen Systeme sofort, wenn in der App etwas passiert. So bleibt Ihr CRM oder Shop immer auf dem neuesten Stand.
Webhook anlegen
Öffnen Sie Einstellungen → Webhooks, tragen Sie die URL ein und wählen Sie die Ereignisse. Nach dem Speichern zeigt die App das Signing-Secret (whsec_…). Kopieren Sie es sofort, es erscheint nur einmal. Per API legen Sie Webhooks mit POST /api/v1/webhooks an.
Ereignisse
contact.created: neuer Kontakt, bei Double-Opt-in nach der Bestätigung.contact.unsubscribed: Abmeldung über Link, One-Click, Antwort oder API.message.bouncedundmessage.complained: Bounce oder Spam-Beschwerde.message.clicked: erster Klick eines Empfängers in einer Mail.campaign.sent: Kampagne fertig versendet.inbox.receivedundinbox.lead: neue Mail im Postfach oder erkannter Lead.
Aufbau der Anfrage
Die App sendet einen POST mit JSON-Body und diesen Headern:
x-newsletter-event: der Name des Ereignisses.x-newsletter-timestamp: Unix-Zeit in Sekunden.x-newsletter-signature:v1=gefolgt von der Signatur in Hex.
{
"event": "contact.unsubscribed",
"createdAt": "2026-11-15T09:30:00.000Z",
"data": { "contactId": "…", "email": "max@example.com", "source": "one_click" }
}Signatur prüfen
Die Signatur ist ein HMAC-SHA256 über Zeitstempel, Punkt und den unveränderten Body, mit Ihrem Signing-Secret als Schlüssel. Prüfen Sie sie immer gegen den rohen Body, bevor Sie ihn verarbeiten:
import crypto from "node:crypto";
const ts = req.headers["x-newsletter-timestamp"];
const sig = req.headers["x-newsletter-signature"]; // "v1=<hex>"
const expected = "v1=" + crypto.createHmac("sha256", SECRET).update(ts + "." + rawBody).digest("hex");
if (sig.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
throw new Error("invalid signature");
}Wiederholungen
Antworten Sie mit einem Status 2xx innerhalb von 10 Sekunden. Andernfalls wiederholt die App die Zustellung mit wachsendem Abstand, bis zu 8 Versuche insgesamt. Der Abstand verdoppelt sich ab 2 Minuten und beträgt höchstens 6 Stunden. Den letzten Status sehen Sie in der Webhook-Liste.