Zum Inhalt springen

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.bounced und message.complained: Bounce oder Spam-Beschwerde.
  • message.clicked: erster Klick eines Empfängers in einer Mail.
  • campaign.sent: Kampagne fertig versendet.
  • inbox.received und inbox.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.

Weiter: MCP-Server verbinden