Ihr Leitfaden für die Nutzung von Webhooks

Sie wissen bereits, dass eine E-Mail nach dem Versand nicht einfach abgehakt ist. Wenn Sie eine Nachricht versenden, möchten Sie diese tracken und auf eventuelle Probleme reagieren, oder? Schließlich hilft Ihnen das Wissen über die Performance Ihrer E-Mails dabei, Ihre Absenderreputation und Zustellbarkeit aufrechtzuerhalten. Indem Sie einen Webhook auf Ihr bevorzugtes CRM verweisen, sieht Ihr Team schnell und einfach relevante Engagement-Metriken ein und trifft Entscheidungen auf Basis aktueller Informationen. Bevor wir uns den Anwendungsfällen widmen, sollten wir die Grundlagen von Webhooks klären.

Einfach ausgedrückt sind Webhooks Benachrichtigungen, die nach Eintritt eines Ereignisses entsprechende Daten an eine andere Anwendung senden. Sie fungieren als umgekehrte API. Anstatt einen API-Endpunkt wiederholt nach Aktualisierungen abzufragen, sendet Ihnen der Webhook das Update über eine HTTP-Anfrage. Webhooks sind für Apps eine Möglichkeit, Informationen durch Automatisierung und benutzerdefinierte HTTP-Callbacks auszutauschen – ähnlich wie bei einer SMS – typischerweise ausgelöst durch ein Ereignis wie eine erfolgreiche E-Mail-Zustellung oder eine Bounce-Benachrichtigung.

In einer ereignisgesteuerten Architektur erweist sich dies als besonders leistungsstark. Wenn Sie beispielsweise Ihrer Banking-App Ihre Einzahlungsinformationen sowie Ihre Telefonnummer mitteilen und die App Ihnen per SMS mitteilt, dass gerade ein Guthaben eingegangen ist, ermöglicht ein Webhook den Versand dieser SMS mit den entsprechenden Updates.

Webhooks werden verwendet, um Benachrichtigungen für bestimmte Ereignisse zu erstellen. Da Webhooks auf HTTP-POST basieren, sind sie einfach zu nutzen. Darüber hinaus lassen sich Webhook-Skripte in fast jeder bevorzugten Skriptsprache schreiben, darunter curl, Ruby, Python, PHP, Java, C# und Go. Sobald die Webhook-Daten erfasst wurden, lassen sie sich in einer Datenbank speichern und nutzen, um die Effektivität von E-Mail-Kampagnen zu messen oder Empfängerprofile zu ergänzen. Nutzen Sie sie in verschiedenen Workflows – von der Protokollierung von E-Commerce-Bestellbestätigungen bis zur Integration von Stripe-Zahlungsereignissen in Echtzeit in Ihr Backend.

Zudem erhalten Sie granularere Daten, als ein Standard-Dashboard liefert, indem Sie die Metriken anpassen, die der Webhook zurückgibt.

Wie funktioniert ein Webhook also?

Wenn das Ereignis eintritt, sendet die Quellseite eine HTTP-POST-Anfrage an eine URL, die vom Entwicklungsteam für den Empfang des Webhooks konfiguriert wurde. Das Entwicklungsteam richtet sie so ein, dass Ereignisse auf einer Seite ein Verhalten auf einer anderen auslösen. Anschließend werden diese Webhook-Daten als Nutzdaten im JSON- oder XML-Format an die konfigurierte URL gesendet. Hier sind die vier erforderlichen Schritte:

Die erste Entscheidung des Entwicklungsteams bei der Planung des E-Mail-Trackings und der Reaktion lautet, welche Daten genau zurückgegeben werden sollen. Falls das Ziel darin besteht, Bounces versendeter E-Mails zu erkennen, führt die URL der nutzenden Person ein Skript für eingehende POST-Anfragen aus, um die betroffene E-Mail-Adresse zu erfassen und in einer lokalen Datenbank zu speichern. Dasselbe Skript lässt sich erweitern, um Empfängernamen, Betreff oder jeden anderen vom Webhook bereitgestellten Parameter zu erfassen.

Sehen wir uns zunächst die Webhook-POST-Anfrage an. Diese wird für die meisten Nachrichten als application/x-www-form-urlencoded und als multipart/form-data codiert, falls der Nachricht ein Anhang beigefügt ist. Die POST-Anfragemethode fordert einen Webserver dazu auf, die im Body der Anfrage-Nachricht enthaltenen Daten zur Speicherung zu akzeptieren.

Hier ist ein Beispiel für einen HTTP-POST von Mailgun an eine URI bei Runescope. Beachten Sie, dass die Kopfzeile für den Content-Type als application/x-www-form-urlencoded festgelegt ist:

                                

                                    ACCEPT: */* 
ACCEPT-ENCODING: GZIP 
CONNECTION: CLOSE 
CONTENT-LENGTH: 1325 
CONTENT-TYPE: APPLICATION/X-WWW-FORM-URLENCODED 
HOST: 
USER-AGENT: MAILGUN/TREQ-0.2.
                                
                            

Der Body der Nachricht enthält Parameter, die als Schlüssel-Wert-Paare gespeichert sind. (Wir gehen im folgenden Abschnitt genauer auf die geposteten Daten ein.) Da die Daten codiert sind, wirken sie auf den ersten Blick unleserlich. So sieht der decodierte Body typischerweise aus:

                                

                                    DOMAIN: BEATNIKZ.NET
EVENT: DELIVERED
MESSAGE-HEADERS: [["RECEIVED", "BY LUNA.MAILGUN.NET WITH HTTP; WED, 07 JAN 2015 00:44:03 +0000"], ["MIME-VERSION", "1.0"], ["CONTENT-TYPE", ["TEXT/PLAIN", {"CHARSET": "ASCII"}]], ["SUBJECT", "HELLO"], ["FROM", "TAG TEST "], ["TO", "MGBOX01@GMAIL.COM"], ["X-MAILGUN-TAG", "WEB APP SEPTEMBER NEWSLETTER"], ["X-MAILGUN-TAG", "NEWSLETTERS"], ["MESSAGE-ID", ""], ["X-MAILGUN-SID", "WYI3NGU3NYISICJTZ2JVEDAXQGDTYWLSLMNVBSISICI0MGRKIL0="], ["DATE", "WED, 07 JAN 2015 00:44:11 +0000"], ["SENDER", "NOLAN=YBEATNIKZ.NET@BEATNIKZ.NET"], ["CONTENT-TRANSFER-ENCODING", ["7BIT", {}]]]
MESSAGE-ID: 
RECIPIENT: MGBOX01@GMAIL.COM
SIGNATURE: EB9FE5C673522299A2259052E56487E54F4D2486A0F1582E91D2C17114A6398
TIMESTAMP: 1420591452
TOKEN: E40542A95B5A6989B5E226CC0E9BB2F120478AF8EE594F884C
X-MAILGUN-SID: WYI3NGU3NYISICJTZ2JVEDAXQGDTYWLSLMNVBSISICI0MGRKIL0=
X-MAILGUN-TAG: WEB APP SEPTEMBER NEWSLETTER
X-MAILGUN-TAG: NEWSLETTERS
                                
                            

Beim Versand einer E-Mail ermöglichen einige ESPs Nutzenden, Daten an ihre Nachrichten anzuhängen, indem sie benutzerdefinierte Daten an die API- oder SMTP-Endpunkte übergeben. Die Daten werden als Kopfzeile in der E-Mail dargestellt und sind typischerweise im JSON-Format. Diese benutzerdefinierten Daten sind dann in allen Webhook-Ereignissen enthalten, die sich auf die jeweilige E-Mail beziehen. Es lassen sich auch mehrere Kopfzeilen einfügen. Deren Werte werden dann kombiniert.

Beispiel:

                                

                                    X-MAILGUN-VARIABLES: {"FIRST_NAME": "JOHN", "LAST_NAME": "SMITH"}
X-MAILGUN-VARIABLES: {"MY_MESSAGE_ID": 123}
                                
                            

So fügen Sie diese Kopfzeile zu einer Nachricht hinzu:

                                

                                    USING API: PASS THE FOLLOWING PARAMETER, "V:MY-CUSTOM-DATA" => "{"MY_MESSAGE_ID": 123}".
USING SMTP: ADD THE FOLLOWING HEADER TO THE EMAIL, "X-MAILGUN-VARIABLES: {"MY_MESSAGE_ID": 123}".
                                
                            

Alternativ löschen Sie einen bestehenden Webhook ganz einfach:

Manchmal ist es hilfreich, den ausgehenden E-Mail-Traffic anhand bestimmter Kriterien zu kategorisieren – beispielsweise, um Anmelde-E-Mails von E-Mails zur Passwortwiederherstellung oder von Kommentaren der Nutzenden zu trennen. Der ESP erlaubt gegebenenfalls, jede ausgehende Nachricht mit einem benutzerdefinierten Wert zu versehen. Diese Werte werden zu Tags, mit denen sich Statistiken zur Zustellbarkeit abrufen oder zusammenfassen lassen. Um einer Webhook-Nachricht ein Tag anzuhängen, fügen Sie ihr ein oder mehrere O:TAG hinzu.

Code-Beispiel für Tagging:

                                

                                    CURL -S --USER 'API:YOUR_API_KEY' \

HTTPS://API.MAILGUN.NET/V3/YOUR_DOMAIN_NAME/MESSAGES \
-F FROM='SENDER BOB ' \
-F TO='ALICE@EXAMPLE.COM' \
-F SUBJECT='HELLO' \
-F TEXT='TESTING SOME MAILGUN AWESOMNESS!' \
-F O:TAG='SEPTEMBER NEWSLETTER' \
-F O:TAG='NEWSLETTERS'
                                
                            

Um die Daten von einem Webhook zu erhalten, geben Nutzende ihrem ESP eine URL an, an die Anfragen zugestellt werden. Das bedeutet, dass sie diese URL auch in ihrer App einrichten müssen, damit sie über das öffentliche Web und von verschiedenen IP-Adressen aus erreichbar ist (daher der Sicherheitsbedarf). Die Webhooks des ESP senden dann POST-Daten im Format application/x-www-form-urlencoded oder multipart/form-data an die URL.

Im letzten Schritt fügen Sie der URL Skripte hinzu, welche die von den Webhooks bereitgestellten Daten erfassen und diese nach Belieben des Entwicklungsteams verarbeiten. Hier werden Sie kreativ und gehen bei den Attributen, die Sie sammeln möchten, granular vor. Dies lässt sich am besten anhand eines Beispiels verdeutlichen.

Ein Anwendungsfall für einen Webhook ist das Tracking von E-Mail-Bounces. Dafür erfassen Sie einen Anhang und speichern die Datei lokal. Der folgende Code nutzt beispielsweise eine Kombination aus dem Python-Microframework Flask und der HTTP-Bibliothek Requests. Hier ist eine kurze Flask-App, um eine Datei aus einem Bounce-Webhook zu erfassen, den ursprünglichen Dateinamen beizubehalten und sie lokal auf Ihrem Webserver zu speichern.

                                

                                    FROM FLASK IMPORT FLASK
FROM FLASK IMPORT REQUEST
FROM WERKZEUG IMPORT SECURE_FILENAME
APP = FLASK(__NAME__)

@APP.ROUTE('/WEBHOOK', METHODS=['GET', 'POST'])
DEF TRACKING():
#CHECKS IF THE REQUEST IS A POST
IF REQUEST.METHOD == 'POST':
F = REQUEST.FILES['ATTACHMENT-1']
# OBTAINS THE FILESTORAGE INSTANCE FROM REQUEST
FILENAME = SECURE_FILENAME(F.FILENAME)
F.SAVE('/HOME/DIRECTORY/WEBHOOK/'+ FILENAME)
PRINT FILENAME
RETURN "OK"
IF __NAME__ == '__MAIN__':
APP.RUN(HOST='0.0.0.0', PORT=100, DEBUG=TRUE)
                                
                            

Um dies in Aktion zu sehen, führen Sie Ihre Anwendung aus und fügen Sie die URL (zum Beispiel: http://yourdomainhere.com:100/webhook) in den Bounce-Webhook ein und klicken auf „Test Webhook“. Sie erhalten eine Datei namens „message.mime“ mit folgendem Inhalt:

                                

                                    RECEIVED: BY LUNA.MAILGUN.NET WITH SMTP MGRT 8734663311733; FRI, 03 MAY 2013 18:26:27 +0000
CONTENT-TYPE: MULTIPART/ALTERNATIVE; BOUNDARY="EB663D73AE0A4D6C9153CC0AEC8B7520"
MIME-VERSION: 1.0
SUBJECT: TEST BOUNCES WEBHOOK
FROM: BOB 
TO: ALICE 
MESSAGE-ID: 
LIST-UNSUBSCRIBE: 
X-MAILGUN-SID: WYIWNZI5MCISICJHBGLJZUBLEGFTCGXLLMNVBSISICI2IL0=
X-MAILGUN-VARIABLES: {"MY_VAR_1": "MAILGUN VARIABLE #1", "MY-VAR-2": "AWESOME"}
DATE: FRI, 03 MAY 2013 18:26:27 +0000
SENDER: BOB_USER_ID@AWESOME_WORKFLOWS.MAILGUN.ORG
--EB663D73AE0A4D6C9153CC0AEC8B7520
MIME-VERSION: 1.0
CONTENT-TYPE: TEXT/PLAIN; CHARSET="ASCII"
CONTENT-TRANSFER-ENCODING: 7BIT
HI ALICE, DO YOU EXIST ON THIS DOMAIN?
--EB663D73AE0A4D6C9153CC0AEC8B7520
MIME-VERSION: 1.0
CONTENT-TYPE: TEXT/PLAIN; CHARSET="ASCII"
CONTENT-TRANSFER-ENCODING: 7BIT
HI ALICE, DO YOU EXIST ON THIS DOMAIN?
--EB663D73AE0A4D6C9153CC0AEC8B7520--
                                
                            

Diese vier Schritte helfen Ihnen bei der Einrichtung eines vollständigen Webhooks. Um davon zu profitieren, lösen Sie ihn aus und machen sich mit den Ereignisparametern vertraut.

Wie oben erklärt, Webhooks werden diese durch bestimmte Ereignisse ausgelöst. Im E-Mail-Bereich gehören dazu Öffnungen, Klicks, Abmeldungen und andere Ereignisse im Zusammenhang mit der E-Mail-Zustellung. Hier ist eine vollständige Übersicht der Mailgun-Ereignisse, die einen Webhook auslösen:

• Open: Dieses Ereignis tritt jedes Mal auf, wenn ein Empfänger eine Nachricht öffnet. Das Öffnungs-Tracking wird aktiviert, indem beim Versand einer Nachricht die Parameter O:TRACKING oder O:TRACKING-OPENS verwendet werden.
• Click: Dieses Ereignis erfasst jeden Klick eines Empfängers auf Links in einer E-Mail-Nachricht. Aktivieren Sie das Klick-Tracking, indem Sie beim Versand einer Nachricht die Parameter O:TRACKING oder O:TRACKING-CLICKS verwenden. Wie bei den Öffnungen müssen die entsprechenden CNAME-Einträge im DNS der nutzenden Person enthalten sein.
• Unsubscribe: Dieses Ereignis tritt auf, wenn ein Empfänger auf den Link zum Abmelden in einer Nachricht klickt. Nutzen Sie das Abmelde-Tracking von Mailgun, um diese Informationen zu erhalten.
• Spam Complaint: Nicht jeder ISP bietet Support für Feedback-Loop-Benachrichtigungen („FBL“) bei Spam-Beschwerden. Stellen Sie jedoch sicher, dass Sie Daten von allen ISPs erhalten, die dies unterstützen.
• Bounce: Eine E-Mail-Nachricht wird als „Bounce“ bezeichnet, falls sie vom SMTP-Server des Empfängers abgelehnt wird. Diese werden oft wie folgt in Hard Bounces oder Soft Bounces unterteilt:
  • Dauerhafter Fehler („Hard Bounce“): Der Empfänger wird nicht gefunden und der E-Mail-Server des Empfängers gibt an, dass der Empfänger nicht existiert. Die App sollte nach einem dauerhaften Fehler den Zustellversuch an ungültige Empfänger einstellen.
  • Vorübergehender Fehler („Soft Bounce“): Die E-Mail wird aufgrund eines vorübergehenden Problems nicht zugestellt, beispielsweise wegen eines vollen Posteingangs. Apps reagieren programmatisch auf vorübergehende Fehler, indem sie eine bestimmte Anzahl von erneuten Versuchen durchführen, bevor sie die Empfängeradresse aus der Liste entfernen.
• Delivered: Eine erfolgreiche Zustellung liegt vor, wenn der E-Mail-Server des Empfängers zurückmeldet, dass er die Nachricht akzeptiert hat. Je nach Ereignis liefern Webhooks verschiedene Parameter, die bei der Identifizierung und Beschreibung der jeweiligen Nachricht helfen. Diese Daten lassen sich dann per Skript zur Analyse parsen. Zu den gängigen Parametern gehören:
  • Ereignis
  • Empfänger
  • Absenderdomain
  • Nachrichtenkopfzeilen
  • Identifizierungsmerkmale des Empfängers: Land, Region, Stadt, Gerät, E-Mail-Client und Betriebssystem

Je nach ESP zählen zu den weiteren Parametern unter anderem benutzerdefinierte Variablen, Tags, Kampagnennamen sowie Authentifizierungs- oder Nutzer-IDs. Darüber hinaus bieten einige Ereignisse weitere Details, wie eine angeklickte URL, einen Grund oder eine Beschreibung für ein negatives Ereignis oder spezielle Codes, die spezifische Ereignisdetails liefern.

Eine empfangende URL muss öffentlich zugänglich sein. Um die Inhalte abzusichern, sollten Webhooks einen Signatur-Zeitstempel sowie ein Token zur Erstellung einer Hashmap enthalten. Eine Hashmap ist lediglich eine Methode, um Elemente mit Identifikatoren zu speichern. Zusätzlich verwendet die Hashmap einen API-Schlüssel, um zu verifizieren, dass die Daten vom ESP des Entwicklungsteams stammen. Programmieren Sie Ihre Anwendung so, dass sie diese Hashmap überprüft, sie mit der des ESP vergleicht und die POST-Anfrage nur zulässt, falls sie übereinstimmt.

Um zu verifizieren, dass der Webhook vom entsprechenden ESP stammt, verknüpfen Sie die Werte für Zeitstempel und Token, codieren den resultierenden String mit dem HMAC-Algorithmus (unter Verwendung des vom ESP bereitgestellten API-Schlüssels als Schlüssel und des SHA256-Digest-Modus) und vergleichen das resultierende Hex-Digest mit der Signatur. Darüber hinaus speichern Sie den Token-Wert lokal im Cache und lehnen alle weiteren Anfragen mit demselben Token ab. Dadurch wird verhindert, dass Hacker das Token verwenden, um Aktionen zu wiederholen oder fehlzuleiten.

Der von Ihnen zurückgegebene Statuscode (z. B. 200 OK) teilt dem Absender mit, ob der Webhook erfolgreich verarbeitet wurde. Überwachen Sie diese Antworten stets, um die Ausfallsicherheit zu gewährleisten. Eine weitere Sicherheitsebene besteht darin, den Zeitstempel zu überprüfen, um sicherzustellen, dass der POST-Versuch innerhalb eines bestimmten Zeitrahmens erfolgt ist.

Nachfolgend finden Sie ein Python-Codebeispiel zur Verifizierung einer Webhook-Signatur:

                                

                                    import hashlib 
import hmac 

def verify(api_key, token, timestamp, signature): 
    message = f"{timestamp}{token}" 
    expected_signature = hmac.new( 
        key=api_key.encode(), 
        msg=message.encode(), 
        digestmod=hashlib.sha256 
    ).hexdigest() 
    return signature == expected_signature
                                
                            

Vollständige Informationen und den Code zum Erstellen und Löschen verschiedener Arten von Webhooks finden Sie in unserer Dokumentation, jedoch haben wir nachfolgend einige gängige Beispiele aufgeführt. Sehen Sie sich diese an.

Über unsere API erstellen Sie ganz einfach einen neuen Webhook:

                                

                                    POST /domains//webhooks
                                
                            

Oder Sie aktualisieren einen bestehenden:

                                

                                    PUT /domains//webhooks/
                                
                            

Alternativ löschen Sie einen bestehenden Webhook ganz einfach:

                                

                                    DELETE /domains//webhooks/
                                
                            

Darüber hinaus rufen Sie für weitere Informationen zu Ihren Webhooks Details zu jeder beliebigen Webhook-URL ab:

                                

                                    GET /domains//webhooks/
                                
                            

Natürlich würden wir den Rahmen sprengen, wenn wir Beispiele für alle Möglichkeiten zeigen würden, wie Sie unsere API zur Erstellung und Optimierung Ihrer Webhooks nutzen können. Der Punkt ist, Sie haben quasi freie Hand (wir verraten es auch nicht weiter).

Obwohl es mehrere Methoden gibt, um auf die durch die E-Mail-Zustellung generierten Daten zuzugreifen, einschließlich ESP-Dashboards und API-Aufrufen, sollten Sie sich das Leben leichter machen und ein paar Webhooks einsetzen. Sie sind die flexibelste und effizienteste Methode, um granulare E-Mail-Nachrichtendaten zu sammeln.

Anstatt Daten von Ihrem ESP abzurufen, entscheiden Sie sich für den kontinuierlichen Erhalt von Push-Daten rund um E-Mails in Echtzeit. Mailgun macht den Umgang mit Webhooks einfach. Das erleichtert Teams die Arbeit, die diese Echtzeit-Informationen nutzen, um Entscheidungen für aktuelle und künftige E-Mail-Kampagnen über verschiedene Web-Anwendungen und -Dienste hinweg zu treffen. Großartig, oder?

Wissen Sie, was noch großartig ist? Weitere Informationen zu Webhooks. Eine einfache Schritt-für-Schritt-Anleitung zur Nutzung von Webhooks mit Mailgun finden Sie in unserer Dokumentation zu Webhooks. Für weitere tiefe Einblicke dieser Art abonnieren Sie unseren Newsletter. Webhooks sind nämlich nicht die einzige Möglichkeit, um an granulare Daten zu gelangen.

Autor: The Sinch Mailgun team The Sinch Mailgun team shares news, best practices, and strategies to take your products and apps to the next level using email. Subscribe to our newsletter to get all the articles in your inbox!