Webhooks

Webhooks informieren externe Systeme über Ereignisse in mail2many. Dabei wird bei bestimmten Events eine externe URL aufgerufen, z. B. bei Opt‑In‑Bestätigung oder Abmeldung.

Als Entwickler kannst du Webhooks nutzen, um dein System zu synchronisieren. Beispielsweise kannst du Opt‑In‑Events für dein CRM oder Opt‑Out‑Events zum Entfernen aus einer eigenen Liste verwenden.

Webhooks erstellen

Webhooks können in den Account‑Einstellungen erstellt werden (Admin‑Rolle erforderlich). Beim Erstellen legst du fest:

• Name – Ein eindeutiger Name für den Webhook
• Events – Welche Ereignisse sollen den Webhook auslösen
• Ziel-URL – Die URL, die aufgerufen werden soll

Ein Account kann mehrere Webhooks mit unterschiedlichen Events und URLs haben:

Account 1 (Kunde A)
│
├─ Webhook 1: "CRM Sync"
│  ├─ Events: optin, optin_additional_channels
│  └─ URL: https://crm.example.com/webhook
│
├─ Webhook 2: "Unsubscribe Handler"
│  ├─ Events: optout, optout_individual_channels
│  └─ URL: https://app.example.com/unsubscribe
│
└─ Webhook 3: "Analytics"
   ├─ Events: optin, optout
   └─ URL: https://analytics.example.com/events

info

Wichtig: Du kannst dieselbe URL für mehrere Events verwenden oder pro Event unterschiedliche URLs anlegen. Die URL muss öffentlich erreichbar, per HTTPS abgesichert und POST‑fähig sein.

Secret & Validierung

Nach dem Erstellen zeigt mail2many ein Webhook‑Secret an. Dieses wird nur einmal angezeigt und muss sicher gespeichert werden – behandle es wie ein Passwort.

info

Sicherheit: Zur Authentifizierung dient der Header X-Mail2Many-Signature. Er enthält eine HMAC‑SHA256‑Signatur aus dem Request‑Body und dem Secret. Vergleiche immer die berechnete Signatur mit dem Header‑Wert, um die Authentizität es empfangenen Aufrufs zu prüfen.

Request‑Format

Bei einem Event sendet mail2many einen POST‑Request an die konfigurierte URL.

HTTP-Header

Die wichtigsten Header:

• X-Mail2Many-Account-Id – Account‑ID
• X-Mail2Many-Event – Event‑Typ
• X-Mail2Many-Event-Date – Zeitpunkt (UTC)
• X-Mail2Many-Event-Id – Eindeutige Event‑ID
• X-Mail2Many-Signature – HMAC‑Signatur zur Validierung

JSON-Payload

Das JSON‑Payload enthält grundlegende Informationen:

• accountId – Account‑ID
• event – Event‑Typ
• date – Zeitpunkt des Events

Zusätzliche Felder hängen vom Event ab (z. B. Empfängerdaten). Details zu den einzelnen Events findest du weiter unten.

Signatur prüfen

Um die Authentizität eines Webhook-Requests zu prüfen, validiere die HMAC-Signatur mit deinem Secret.

Beispiel: PHP

$secret = 'your_webhook_secret';

$headers = getallheaders();

$payload = file_get_contents('php://input');

$signature = $headers['X-Mail2many-Signature'] ?? '';

$computedSignature = hash_hmac('sha256', $payload, $secret);

if (hash_equals($computedSignature, $signature)) {

    // Request ist authentisch
    $data = json_decode($payload, true);

    // Webhook-Daten verarbeiten
    http_response_code(200);
    exit;
} else {

    // Request ist nicht authentisch
    http_response_code(401);
    exit;
}

Sicherheitshinweise

Webhook‑Metadaten (Event‑ID, Zeitstempel, Event, Signatur) liegen in den HTTP‑Headern. So kann die Authentizität geprüft werden, bevor der Body geparst wird. Das erleichtert frühe Ablehnung ungültiger Requests und entspricht Best Practices vieler Plattformen.

Best Practices:

• Validiere die Signatur mit dem Roh‑Body
• Prüfe das Zeitfenster (Event‑Date)
• Stelle sicher, dass die Event‑ID nicht doppelt verarbeitet wird (Replay‑Angriffe verhindern)
• Die URL muss öffentlich erreichbar sein und einen 2xx‑Statuscode liefern

info

Wichtig: Wenn deine URL nicht erreichbar ist oder keine 2xx‑Response liefert, wird der Webhook mehrfach erneut versucht und schließlich als fehlgeschlagen markiert.

Verfügbare Events

mail2many unterstützt aktuell folgende Webhook-Events:

Event	Name	Beschreibung
optin	Opt‑In Bestätigung	Empfänger war inaktiv, bestätigt Opt‑In und ist jetzt aktiv.
optin_additional_channels	Opt‑In Bestätigung (zusätzliche Kanäle)	Empfänger war bereits in mindestens einem Kanal aktiv und bestätigt Opt‑In für zusätzliche Kanäle.
optout	Vollständige Abmeldung	Empfänger war aktiv, meldet sich von allen Kanälen ab und ist jetzt inaktiv.
optout_individual_channels	Abmeldung (einzelne Kanäle)	Empfänger meldet sich von einzelnen Kanälen ab, bleibt aber in mindestens einem Kanal aktiv.

Event-Payloads

Alle Events verwenden dasselbe Grund‑Payload mit folgenden Feldern:

Key	Beschreibung	Beispiel
accountId	ID des Accounts, in dem das Event passiert ist.	1
event	Event‑Typ.	optin
date	Zeitpunkt des Events (UTC).	2025-11-27 09:52:31
email	E‑Mail des Empfängers.	john.doe@example.com
title	Akademischer Titel.	Dr.
firstname	Vorname.	John
lastname	Nachname.	Doe
genderId	Geschlecht: 1=male, 2=female, 3=non-binary, 4=not specified.	1
ip	IP‑Adresse beim Event.	192.168.1.1
channelIds	IDs der Kanäle, die (ab)bestellt wurden.	[1, 2]
newsletterId	ID des Newsletters.	1
newsletterSubject	Betreff des Newsletters.	Welcome to our newsletter!

Weitere Events werden in Zukunft ergänzt. Bei speziellen Anforderungen wende dich bitte an den Support.