Ein praktischer Leitfaden zur Nutzung von Mailgun-Webhooks

Dieser Gastbeitrag stammt von Opeyemi Obembe, einem Mailgun-Kunden aus Nigeria. Als wir das Tutorial von Opeyemi zur Einrichtung von Webhooks sahen, wussten wir, dass wir es mit Ihnen teilen mussten. Die Methodik von Opeyemi ist nicht nur absolut verlässlich, sondern Opeyemi ist auch genau der Typ Profi aus der Entwicklung, den wir gerne unterstützen.

Opeyemi hat sich vor vier Jahren bei Mailgun registriert und seitdem einige wirklich herausragende Dinge entwickelt. Zuletzt hat Opeyemi Suet entwickelt, ein Open-Source-Projekt, das detaillierte Analysen und Berichte für über Mailgun versendete Transaktions-E-Mails bietet. Nutzen Sie es in Kombination mit unseren neuen Analysen-Funktionen, um zusätzliche Einblicke in Ihr E-Mail-Engagement zu erhalten.

Transaktions-E-Mails sind für die meisten Apps unerlässlich. Wir versenden Willkommens-E-Mails, E-Mails zur Passwort-Wiederherstellung, Benachrichtigungen und mehr. Und dafür nutzen wir Anbieter wie Mailgun. Der E-Mail-Versand ist großartig, aber wie sieht es mit der Zustellung und Leistung aus? Hat dieser Nutzer diese E-Mail zum Zurücksetzen des Passworts erhalten? Wurde diese Benachrichtigungs-E-Mail über eine ablaufende Kreditkarte geöffnet?

Obwohl diese Daten in Ihrem Mailgun-Konto-Dashboard verfügbar sind, besteht eine weitere Möglichkeit, Updates zu Ihren Transaktionsnachrichten in Mailgun zu erhalten, über Webhooks. Es gibt auch die API, aber im Gegensatz zur API, bei der Sie diese Updates „anfragen“ (Poll), werden Ihnen die Updates bei Webhooks direkt gesendet (Push). Sie müssen lediglich die URL eines Skripts angeben, das die Event-Daten über POST verarbeiten kann.

Natürlich bietet Push einige Vorteile gegenüber Poll.

• Sie müssen keine wiederholten API-Anfragen stellen. Dadurch werden weniger Serverressourcen verbraucht.
• Updates erfolgen eher in Echtzeit, da sie gesendet werden, sobald sie auf dem Server verfügbar sind.

Es gibt zwei Möglichkeiten, Webhooks in Mailgun einzurichten. Dies kann entweder über das Mailgun-Dashboard erfolgen oder API. Der unkompliziertere Weg führt über das Dashboard. Sobald Sie in Ihrem Dashboard eingeloggt sind, steht ein Webhooks-Link  in der Navigationsleiste zur Verfügung.

Auf der Webhooks-Seite sind die verschiedenen Event-Typen aufgeführt, für die Sie Event-Daten erhalten können. Indem Sie auf das Symbol „+“ vor jedem Event klicken, können Sie die URL festlegen, an die die Event-Daten gesendet werden.

Um die an unsere Webhook-URL gesendeten Event-Daten zu verarbeiten, müssen wir zunächst wissen, wie die Daten aussehen werden. Die per POST gesendeten Parameter sind in der API-Dokumentation. Wir können noch einen Schritt weiter gehen und dies bestätigen, indem wir eine Test-Webhook-URL verwenden, die die Daten von Mailgun protokolliert. Dafür können wir Mailguns Postbin oder requestb.in. Diese Dienste generieren einen eindeutigen Endpunkt, den wir im Mailgun-Dashboard nutzen können, um Beispiel-Event-Daten zu erhalten. Ich empfehle requestbin, da es mehr Details wie die Anfrage-Kopfzeilen bereitstellt. Diese Kopfzeilen sind wichtig, da man leicht übersieht, dass Mailgun einige Daten mit dem Inhaltstyp [application/x-www-form-urlencoded] und andere als [multipart/form-data] sendet. Wenn diese kleinen Details fehlen, ändert sich die Art und Weise, wie Sie die Event-Daten erhalten, grundlegend.

Lassen Sie uns einen Test-Endpunkt erstellen und sehen, wie die Event-Daten im Vergleich zu den Angaben in der Dokumentation aussehen.

• Weitere Informationen zu requestb.in und einen Bin erstellen.
• Kopieren Sie die URL und öffnen Sie den Webhooks-Bereich Ihres Mailgun-Dashboards.
• Fügen Sie die URL in das Eingabefeld ein und klicken Sie auf den Link „Test Webhook“. Dadurch werden Beispiel-Event-Daten an die URL gesendet.

• Wiederholen Sie dies für alle Events, die für Sie von Interesse sind.
• Aktualisieren Sie Ihre requestbin-Seite, um die gesendeten Event-Daten anzuzeigen.

Wenn Sie sich die requestbin-Daten genau ansehen, werden Sie bemerken, was zuvor über die als multipart/form-data gesendeten Daten erwähnt wurde.

Da wir nun wissen, welche Parameter für jeden Event-Typ gelten und welchen Inhaltstyp sie haben können, ist es einfach, Code zur Verarbeitung der gesendeten Daten zu schreiben. Hier ist ein einfacher Code, der Details zu Beschwerden und verworfenen E-Mails ausgibt. (Ich verwende multer zur Verarbeitung von multipart/form-data.)

                                

                                    const express = require('express')  rn    , bodyParser = require('body-parser')rn    , multer = require('multer')rn    ;rnrnconst app = express();  rnapp.use(bodyParser.urlencoded({extended: false}));  rnapp.listen(process.env.PORT || 3000);rnrnapp.post('/webhook', multer().none(), function(req, res) {  rn  const email = req.body.recipient;rn  const event = req.body.event;rnrn  if (event == 'complained') {rn    console.log(<code data-enlighter-language="generic" class="EnlighterJSRAW">${email} complained about your mail</code>);rn  }rn  else if (event == 'dropped') {rn    console.log(<code data-enlighter-language="generic" class="EnlighterJSRAW">Mail to ${email} dropped. ${event.description}</code>);rn  }rn  else if (event == 'bounced') {rn    console.log(<code data-enlighter-language="generic" class="EnlighterJSRAW">Error ${event.code}: Mail to ${email} bounced. ${event.error}</code>);rn  }rnrn  res.end();rn});
                                
                            

Nichts hindert jemanden, der unsere Webhook-URL kennt, daran, falsche Event-Daten zu erstellen und an die URL zu senden. Zum Glück signiert Mailgun jede gesendete Anfrage und übermittelt auch die folgenden Parameter:

• timestamp (Anzahl der seit dem 1. Januar 1970 vergangenen Sekunden)
• token (zufällig generierter String mit einer Länge von 50 Zeichen)
• signature (durch einen HMAC-Algorithmus generierter hexadezimaler String)

Um das Token zu verifizieren, müssen Sie Folgendes tun:

• Die Werte von timestamp und token verketten.
• Den resultierenden String mit HMAC codieren, wobei Ihr HTTP-Webhook-Signaturschlüssel als Schlüssel und Sha256 als Algorithmus verwendet wird.

Das Ergebnis sollte mit der Signatur übereinstimmen.

So sieht das in Node.js aus:

                                

                                    const value = event_data_timestamp+event_data_token;  rnconst hash = crypto.createHmac('sha256', apikey)  rn                   .update(value)rn                   .digest('hex');rnif (hash !== event_data_signature) {  rn  console.log('Invalid signature');rn  return;rn}
                                
                            

Wenn wir das zu unserem ursprünglichen Code-Beispiel hinzufügen, sieht das in etwa so aus:

                                

                                    const express = require('express')  rn    , crypto = require('crypto')rn    , multer = require('multer')rn    , bodyParser = require('body-parser')rn    ;rnrnconst app = express();  rnapp.use(bodyParser.urlencoded({extended: false}));  rnapp.listen(process.env.PORT || 3000);rnrnapp.get('/webhook', multer().none(), function(req, res) {  rn  // Validate signaturern  const value = req.body.timestamp+req.body.token;rn  const hash = crypto.createHmac('sha256',rn              process.env.API_KEY)rn                   .update(value)rn                   .digest('hex');rn  if (hash !== req.body.signature) {rn    console.log('Invalid signature');rn    return res.end();rn  }rnrn  // Log status of eventrn  const email = req.body.recipient;rn  const event = req.body.event;rnrn  if (event == 'complained') {rn    console.log(<code data-enlighter-language="generic" class="EnlighterJSRAW">${email} complained about your mail</code>);rn  }rn  else if (event == 'dropped') {rn    console.log(<code data-enlighter-language="generic" class="EnlighterJSRAW">Mail to ${email} dropped. ${event.description}</code>);rn  }rn  else if (event == 'bounced') {rn    console.log(<code data-enlighter-language="generic" class="EnlighterJSRAW">Error ${event.code}: Mail to ${email} bounced. ${event.error}</code>);rn  }rnrn  res.end();rn});
                                
                            

Wir können das sogar noch erweitern und:

• Für jede Anfrage eine Überprüfung anhand eines Token-Caches durchführen, um die Verwendung desselben Tokens zu verhindern. Jedes Token wird dort gespeichert. Dies verhindert Replay-Angriffe.
• Überprüfen, ob der Zeitstempel nicht zu weit von der aktuellen Uhrzeit entfernt ist.

Wenn Sie viele E-Mails versenden und viele Events erwarten, ist es keine gute Idee, Ihr Webhook-Skript auf einem Server abzulegen, der nicht automatisch skaliert. Selbst wenn Sie nicht viele Events erwarten, können unerwartete Vorfälle zu einem sprunghaften Anstieg führen. In solchen Fällen ist ein Server, der automatisch skaliert, äußerst nützlich.

Hier kommt Serverless Computing. Einfach ausgedrückt besteht die Idee darin, dass Sie die Ausführung Ihres Codes und alle damit verbundenen Aufgaben an einen Anbieter delegieren können. Mehrere Instanzen Ihres Codes können parallel ausgeführt werden, und Sie können Rechenressourcen wie RAM sowie die Ausführungszeit spontan anpassen. Dadurch wird eine hohe Skalierbarkeit erreicht. Zudem erfolgt die Abrechnung basierend auf den verbrauchten Ressourcen und der Ausführungszeit. Es kann also sehr kostengünstig sein, wenn Sie nicht regelmäßig viele E-Mails versenden.

Es gibt einige Anbieter für Serverless Computing. Ein Anbieter, den ich nutze und empfehle, ist Google Cloud Functions , da sich HTTP-Funktionen damit sehr einfach einrichten lassen. Eine HTTP-Funktion ist ein Codeblock, der als Funktion verpackt ist und durch das Aufrufen einer URL getriggert werden kann. Genau das benötigen wir für unseren Webhook.

Um diese Funktion zu erstellen, müssen wir eine JavaScript-Funktion schreiben, die als Node.js-Modul exportiert wird. Die Funktion erfordert HTTP-spezifische Argumente: request und response.

                                

                                    exports.webhook = function(request, response) {  rn  // Handle event data herern  response.send({status:"ok"});rn}
                                
                            

Basierend auf dem Inhaltstyp der Anfrage wird der Body der Anfrage automatisch übergeben und ist im Parameter body des Anfrage-Objekts verfügbar.

                                

                                    exports.webhook = function(request, response) {  rn  let event = request.body.event; // deliveredrn  // Handle event data herern  // ...rn  response.send({status:"ok"});rn}
                                
                            

Dies funktioniert jedoch nicht beim Inhaltstyp multipart/form-data. Und wie wir bereits wissen, sendet Mailgun einige Daten als multipart/form-data. Wir können eine Bibliothek wie Multer mithilfe von require() einbinden. Wir müssen jedoch sicherstellen, dass die Abhängigkeit in der Datei package.json aufgeführt ist.

                                

                                    const multer = require('multer');rnrnexports.webhook = function(request, response) {  rn  parser(request, response, function(){rn    console.log(request.body); // Our event datarn    // Handle event data herern    // ...rn    response.send({status:"ok"});rn  });rn}
                                
                            

                                

                                    {rn  "dependencies": {rn    "multer": "^1.3.0"rn  }rn}
                                
                            

Als Nächstes können wir die Funktion in Cloud Functions.  veröffentlichen. Ein einfacher Weg dafür ist das Cloud Functions-Dashboard.

• Öffnen Sie Ihre Google Cloud Console (falls Sie noch kein Konto haben, erstellen Sie eines).
• Aktivieren Sie Cloud Functions im Dashboard.
• Klicken Sie auf „Funktion erstellen“.
• Geben Sie einen Namen für Ihre Funktion ein (z. B. „mailgun-webhook“).
• Wählen Sie im Bereich für Trigger „HTTP-Trigger“ aus. Notieren Sie sich die URL, denn dies ist Ihre Webhook-URL.
• Kopieren Sie Ihren Code zur Verarbeitung der Event-Daten in den Bereich index.js der Cloud-Funktion.
• Kopieren Sie den Inhalt Ihrer package.json und fügen Sie ihn im Bereich package.json ein.
• Wählen Sie ein Stage-Bucket aus oder erstellen Sie eines. Das Stage-Bucket ist einfach der Ort, an dem der Code bereitgestellt wird. Hier können Sie alles Beliebige verwenden.
• Geben Sie unter Auszuführende Funktion den Namen Ihrer Funktion ein (z. B. „webhook“).
• Speichern.

Verwenden Sie nun die URL der Funktion in Mailgun als Ihre Webhook-URL.

Das Arbeiten mit Mailgun-Webhooks ist unkompliziert. Es gibt viele Möglichkeiten, die Event-Daten zu nutzen, um Ihre Anwendungen außerhalb von Mailgun anzureichern. Wenn Sie beispielsweise Ihrer Nutzerschaft ermöglichen, E-Mails aus irgendeinem Grund von Ihrer Website zu versenden, und Sie Mailgun nutzen, verwenden Sie Webhooks, um ihnen Analysen bereitzustellen. Oder vielleicht möchten Sie Ihre E-Mail-Analysen an eine andere Plattform senden. Oder vielleicht möchten Sie über Fehler in Ihrer Slack Konto. Vielleicht auch das nicht, sondern Sie möchten einfach nur detailliertere Analysen. Was auch immer der Anwendungsfall ist, die Event-Daten stehen Ihnen zur Verfügung.

Ein Praxisbeispiel finden Sie im Quellcode der Webhook-Datei von Suet.

Möchten Sie Mailgun-Webhooks ausprobieren? Registrieren

Und falls Sie Starthilfe bei Mailgun benötigen, sehen Sie sich dieses kostenlose Mailgun-Training an! Unser Team Lead of Customer Support, Chris Hammer, führt Sie durch den Einrichtungsprozess und hilft Ihnen bei den ersten Schritten zum Senden, Empfangen und Tracken Ihrer E-Mails mit Mailgun.

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!