Einen Webhook einrichten

Ein Webhook ist eine Adresse auf Ihrem eigenen Server, an die 2Mail eine Meldung schickt, sobald mit einer E-Mail etwas geschieht: zugestellt, gebounct, geöffnet. So weiß Ihr Onlineshop oder Ihr CRM innerhalb weniger Sekunden, was mit einer Nachricht passiert ist, ohne dass Sie ins Dashboard schauen müssen.

Was Sie brauchen

• eine Adresse auf Ihrem Server, die über https erreichbar ist und Anfragen entgegennehmen kann; ein Webhook ohne Verschlüsselung wird nicht akzeptiert
• ein Stück Code hinter dieser Adresse, das die Daten verarbeitet
• Administratorrechte in Ihrem 2mail-Konto

Schritt 1: den Webhook anlegen

1. Öffnen Sie im Dashboard den Bereich mit den Webhooks und legen Sie einen neuen an.
2. Tragen Sie die Adresse Ihres Endpunkts ein.
3. Wählen Sie die Ereignisse, die Sie empfangen möchten: Zustellung, Bounce, Öffnung oder eine Kombination. Fangen Sie mit Bounces an — das ist das Ereignis, auf das Sie am schnellsten reagieren müssen.
4. Speichern Sie. Das Dashboard zeigt einen geheimen Schlüssel, mit dem jeder Aufruf signiert wird. Legen Sie ihn in der Konfiguration Ihrer Anwendung ab.

Schritt 2: die Signatur prüfen

Jeder kann eine Anfrage an Ihre Adresse schicken. Jeder Aufruf von 2Mail trägt deshalb eine Signatur im Header, berechnet mit dem geheimen Schlüssel über den Inhalt. Berechnen Sie diese Signatur auf Ihrer Seite erneut und weisen Sie Anfragen zurück, bei denen sie nicht stimmt. Überspringen Sie diesen Schritt nicht: Ohne Prüfung kann ein Außenstehender Ihrem System vorgaukeln, eine Nachricht sei gebounct.

Schritt 3: schnell antworten

Antworten Sie sofort mit einem Statuscode aus der 200er-Reihe und verarbeiten Sie die Daten danach, zum Beispiel über eine Warteschlange. Dauert Ihre Verarbeitung zu lange oder antworten Sie mit einem Fehler, betrachtet 2Mail den Aufruf als fehlgeschlagen und versucht es später erneut. Sorgen Sie dafür, dass Ihr Code dieselbe Meldung zweimal empfangen kann, ohne doppelte Aktionen auszulösen: Verwenden Sie die Kennung der Nachricht, um Wiederholungen zu erkennen.

Schritt 4: testen

Senden Sie eine Test-E-Mail an eine Adresse, die Sie verwalten, und schauen Sie, ob die Zustellung an Ihrem Endpunkt eintrifft. Für einen Bounce testen Sie mit einer Adresse, die es auf einer existierenden Domain sicher nicht gibt. Das Dashboard zeigt je Webhook die letzten Aufrufe, mit der Antwort Ihres Servers — dort sehen Sie sofort, ob Ihr Endpunkt etwas anderes als eine 200 zurückgegeben hat.

Was Sie damit machen

• Bei einem Hard Bounce die Adresse in Ihrem CRM markieren, damit ein Vertriebsmitarbeiter sie nicht weiter verwendet.
• Bei einer Zustellung in der Bestellhistorie anzeigen, dass die Bestätigung angekommen ist — das spart Telefonate.
• Bei einer Öffnung eine Folgeaufgabe planen, zum Beispiel nach einem Angebot.

Wo es schiefgeht

• Keine Aufrufe — die Adresse ist nur intern erreichbar, oder eine Firewall blockiert Anfragen von außen.
• Signatur stimmt nie — Sie berechnen sie über einen veränderten Inhalt; verwenden Sie den rohen Inhalt der Anfrage.
• Doppelte Aktionen — Ihr Endpunkt antwortet zu langsam und bekommt deshalb Wiederholungen.

Webhooks gehören zur E-Mail-API; einen API-Schlüssel erstellen ist der erste Schritt, wenn Ihre Anwendung auch versenden soll.

Klappt es nicht?

Geben Sie uns über Kontakt die Adresse Ihres Endpunkts und die Uhrzeit des Tests durch. Wir zeigen Ihnen, was Ihr Server uns geantwortet hat.