Die folgende einfache Anleitung soll Absendern helfen, sich wohl zu fühlen, wenn sie ein Bird-Events-WebHook erstellen und die Daten mit der Infrastruktur von AWS konsumieren.
Bird’s Echtzeit-Event-Webhooks sind ein unglaublich wertvolles Werkzeug für Absender, um Daten automatisch in ihre Systeme übertragen zu lassen. Dies kann nachgelagerte Automatisierungsvorgänge wie das Aktualisieren von Mailinglisten, das Auslösen automatisierter E-Mail-Reisen oder das Befüllen interner Dashboards ermöglichen. Während dieselben Ereignisdaten über das Bird UI mithilfe von Event Search oder programmatisch durch die Nutzung der Bird Events API abgerufen werden können, können Beschränkungen hinsichtlich der Anzahl von Datensätzen, die in einer einzigen Anfrage zurückgegeben werden, oder Geschwindigkeitsbegrenzungen, die für den API-Endpunkt gelten, beide Methoden für große und anspruchsvolle Absender einschränkend machen.
Echtzeit-Event-Webhooks ermöglichen es einem Absender, einen Endpunkt zu konfigurieren, an den Bird die Daten überträgt, und die Daten können konsumiert werden, ohne dass Cron-Jobs geplant werden müssen, die die Daten abrufen. Es gibt auch logistische Kompromisse, wenn Sie die Daten abrufen, anstatt sie an Sie senden zu lassen, wie z. B. die Notwendigkeit festzulegen, welchen Zeitraum und welche Parameter für jede API-Anfrage verwendet werden sollen. Wenn die Zeiträume nicht perfekt übereinstimmen, riskieren Sie, Daten zu verpassen, und wenn die Zeiträume sich überschneiden, müssen Sie doppelte Datensätze handhaben. Mit Echtzeit-Webhooks werden Ereignisdaten einfach an Ihren Endpunkt gesendet, sobald sie innerhalb von Bird verfügbar werden.
Während die Vorteile des Empfangs von Ereignisdaten in Echtzeit zur Steuerung nachgelagerter Automatisierungsprozesse von vielen Absendern sofort verstanden werden, kann der eigentliche Prozess der Implementierung und Nutzung von Webhooks einschüchternd wirken. Dies kann besonders dann zutreffen, wenn Sie mit den technischen Komponenten der Erstellung eines Endpunkts und der programmatischen Verarbeitung der Daten nicht vertraut sind. Es gibt Dienste, die Bird-Webhook-Daten konsumieren und automatisch in Ihre Datenbank ETL durchführen – ein Beispiel wäre StitchData, über das wir in der Vergangenheit gebloggt haben. Wenn Sie jedoch mehr Kontrolle über den Prozess wünschen, können Sie die Komponenten problemlos selbst erstellen. Das Folgende ist ein einfacher Leitfaden, damit sich Absender wohlfühlen, wenn sie einen Bird-Events-Webhook erstellen und die Daten mit der Infrastruktur innerhalb von AWS konsumieren.
Konfigurieren des Webhook Target Endpoint
Wenn ein Bird-Ereignis erstellt wird, möchten wir, dass die Ereignisdaten in Echtzeit an einen Endpunkt in AWS gestreamt werden, damit wir die Daten programmatisch konsumieren und nutzen können. Die Daten werden von Bird an einen Zielendpunkt gesendet, der die Nutzlast an eine Lambda-Funktion weiterleitet, die die Daten verarbeitet und in einem S3-Bucket speichert. Ein schematisches Diagramm des beschriebenen Datenflusses ist unten zu sehen:
Um diesen Workflow zu implementieren, bauen wir ihn tatsächlich in umgekehrter Reihenfolge auf, beginnend mit der Erstellung eines S3-Buckets, in dem wir unsere Ereignisdaten speichern, und arbeiten dann rückwärts – indem wir jede Komponente hinzufügen, die zu dem beiträgt, was wir bereits gebaut haben.
Erstellen Sie einen S3-Bucket zum Speichern der Webhook-Daten
Bevor wir unseren Load Balancer erstellen, um die Daten zu akzeptieren, oder unsere Lambda-Funktion, um die Daten zu speichern, müssen wir zuerst unseren S3-Bucket erstellen, in dem die Daten gespeichert werden. Während S3 exzellenten Speicher für Webhook-Daten bietet, sollten Organisationen, die auch PostgreSQL-Datenbanken für die Ereignisverarbeitung verwenden, ordnungsgemäße Backup- und Wiederherstellungsverfahren implementieren, um ihre strukturierten Daten neben ihrer S3-Speicherstrategie zu schützen. Dazu navigieren Sie zum S3-Dienst innerhalb von AWS und drücken „Bucket erstellen“. Sie werden aufgefordert, Ihrem Bucket einen Namen zu geben und die Region festzulegen – stellen Sie sicher, dass Sie dieselbe Region wie Ihr ALB und die Lambda-Funktion verwenden. Wenn Ihr S3-Bucket erstellt wird, ist er leer – wenn Sie die Daten in einem Ordner organisieren möchten, können Sie entweder das beabsichtigte Verzeichnis jetzt erstellen oder das Verzeichnis wird erstellt, wenn Ihre Lambda-Funktion die Datei speichert. In diesem Beispiel haben wir unseren S3-Bucket „bird-webhooks“ genannt und einen Ordner namens „B Event Data“ erstellt, um unsere Ereignisdaten zu speichern – diese Namen werden in unserer Lambda-Funktion unten erwähnt.
Erstellen Sie eine Lambda-Funktion, um die Daten zu konsumieren
Die eigentliche Verarbeitung und Speicherung der Daten wird von einer Lambda-Funktion durchgeführt, die von unserem Application Load Balancer (ALB) aufgerufen wird.
Der erste Schritt besteht darin, Ihre Lambda-Funktion zu erstellen, indem Sie zum Lambda-Dienst innerhalb von AWS navigieren und auf „Funktion erstellen“ klicken. Sie werden aufgefordert, Ihrer Lambda-Funktion einen Namen zuzuweisen und auszuwählen, welche Programmiersprache Sie für Ihre Funktion verwenden möchten. Für dieses Beispiel verwenden wir Python als Laufzeitumgebung.
Jetzt müssen wir unsere Lambda-Funktion entwickeln. Nehmen wir einen Moment an, dass unser Application Load Balancer konfiguriert wurde und die Webhook-Nutzlast an unsere Lambda-Funktion weiterleitet – die Lambda erhält eine Nutzlast, die die vollständigen Header und den Body enthält. Die Nutzlast wird als Wörterbuch im Objekt „event“ an unsere Lambda-Funktion übergeben. Sie können unabhängig auf die Header und den Body der Nutzlast zugreifen, indem Sie auf die Objekte „headers“ und „body“ innerhalb der Nutzlast zugreifen. In diesem Beispiel werden wir einfach den „x-messagesystems-batch-id“-Header lesen, bei dem die Batch-ID ein eindeutiger Wert ist, der von Bird für den Webhook-Batch erstellt wurde und den wir als Dateinamen verwenden, wenn wir den Body in S3 als Flatfile speichern; jedoch könnten Sie zusätzliche Funktionalitäten wie Authentifizierungsprüfungen oder Fehlerbehandlung hinzufügen, falls benötigt.
Bei der Speicherung der Nutzlast in einem Flatfile auf S3 müssen wir den Namen des S3-Buckets, den Speicherort und den Dateinamen der Datei definieren, in der die Nutzlastdaten gespeichert werden. In unserer Beispiel-Lambda-Funktion machen wir dies innerhalb der „store_batch“-Funktion. In diesem Beispiel werden wir das gesamte Batch als einzelne Datei speichern, was dazu beiträgt, sicherzustellen, dass die Daten gesammelt und gespeichert werden, bevor die HTTP-Verbindung zwischen Bird und Ihrem Endpunkt abläuft. Während Sie die Verbindungstimeout-Einstellungen auf Ihrem Load Balancer anpassen könnten, gibt es keine Garantie, dass die Verbindung nicht auf der Übertragungsseite (in diesem Fall Bird) oder dass die Verbindung nicht beendet wird, bevor Ihre Lambda-Funktion fertig ausgeführt wird. Es ist eine bewährte Praxis, Ihre Konsumentfunktion so effizient wie möglich zu halten und Datenverarbeitungsaktivitäten für nachgelagerte Prozesse zu reservieren, wo möglich – wie das Konvertieren der batched JSON-formatierten Nutzlast in eine CSV-Datei oder das Laden der Ereignisdaten in eine Datenbank.
Es ist wichtig zu beachten, dass Sie möglicherweise die Berechtigungen für Ihre Lambda-Funktion aktualisieren müssen. Ihre Ausführungsrolle benötigt PutObject- und GetObject-Berechtigungen für S3. Es ist eine bewährte Praxis, das Prinzip der minimalen Rechte durchzusetzen, daher empfehle ich, diese Berechtigungen nur für den S3-Bucket festzulegen, in dem die Webhook-Nutzlasten gespeichert werden.
Ein Beispiel unserer Konsumenten-Lambda-Funktion finden Sie hier.
Ein kurzer Hinweis zur Batch-ID: Bird wird Ereignisse zu einer einzelnen Nutzlast bündeln, wobei jeder Batch 1 bis 350 oder mehr Ereignisdatensätze enthalten kann. Der Batch erhält eine eindeutige Batch-ID, die verwendet werden kann, um den Batch-Status entweder über die Nutzung der Event Webhooks API zu überprüfen oder innerhalb Ihres Bird-Kontos, indem Sie auf einen Webhook-Stream klicken und „Batch-Status“ auswählen. Falls eine Webhook-Nutzlast nicht zugestellt werden konnte, beispielsweise bei einem Verbindungstimeout, wird Bird automatisch den Batch erneut versuchen mit derselben Batch-ID. Dies kann passieren, wenn Ihre Lambda-Funktion nahe an der maximalen Round-Trip-Zeit von 10 Sekunden läuft und ist ein Grund, die Konsumentenfunktion zu optimieren, um die Ausführungszeit zu reduzieren.
Um alle Datenverarbeitungsaktivitäten zu bewältigen, empfehle ich, eine separate Lambda-Funktion zu erstellen, die immer dann ausgeführt wird, wenn eine neue Datei auf dem S3-Bucket erstellt wird – auf diese Weise wird die Datenverarbeitung asynchron zur Datenübertragung durchgeführt, und es besteht kein Risiko, Daten aufgrund einer unterbrochenen Verbindung zu verlieren. Ich bespreche die Verarbeitung der Lambda-Funktion in einem späteren Abschnitt.
Erstellen Sie einen Application Load Balancer
Um eine Webhook-Nutzlast zu empfangen, müssen wir einen Endpunkt bereitstellen, an den die Nutzlasten gesendet werden. Dies tun wir, indem wir einen Application Load Balancer innerhalb von AWS erstellen, indem wir zu EC2 > Load Balancers navigieren und auf „Load Balancer erstellen“ klicken. Sie werden aufgefordert, auszuwählen, welchen Typ von Load Balancer Sie erstellen möchten – dafür möchten wir einen Application Load Balancer erstellen. Wir müssen einen Application Load Balancer (ALB) verwenden, um unseren Konsumenten aufzubauen, da die Ereigniswebhooks als HTTP-Anforderung gesendet werden und ALBs zum Routing von HTTP-Anforderungen innerhalb von AWS verwendet werden. Wir könnten ein HTTP Gateway als Alternative implementieren; jedoch verwenden wir für dieses Projekt einen ALB, weil er leichter und kostengünstiger ist als ein HTTP Gateway. Es ist wichtig zu beachten, dass wenn Sie ein HTTP Gateway verwenden, das Ereignisformat möglicherweise anders ist als bei einem ALB und daher Ihre Lambda-Funktion das Anfrageobjekt entsprechend behandeln muss.
Sobald Ihr ALB erstellt ist, werden Sie aufgefordert, Ihrem ALB einen Namen zu geben und das Schema sowie die Zugangs-/Sicherheitseinstellungen zu konfigurieren – da wir planen, Ereignisdaten von einer externen Quelle (Bird) zu empfangen, möchten wir, dass unser ALB internetorientiert ist. Unter „Listeners and routing“ sollte der ALB auf HTTPS auf Port 443 hören, und wir möchten eine Zielgruppe erstellen, die auf unsere Lambda-Funktion zeigt, damit unser ALB eingehende Anforderungen an die oben erstellte Konsumenten-Lambda-Funktion weiterleitet. Sie müssen auch sicherstellen, dass die Sicherheitsgruppe die Berechtigung hat, Verkehr über Port 443 zu akzeptieren.
Erstellen Sie einen DNS-Eintrag für den Load Balancer
Um es einfacher zu machen, unseren ALB als Endpunkt zu nutzen, erstellen wir einen A-Record im DNS, der auf unseren ALB zeigt. Dafür können wir den AWS Route 53 Dienst (oder Ihren aktuellen DNS-Anbieter) verwenden und einen A-Record für den Hostnamen erstellen, den Sie für Ihren Endpunkt verwenden möchten (z.B. spevents.<your_domain>). Wenn Sie mit DNS in großem Maßstab auf AWS arbeiten, beachten Sie, dass es undokumentierte DNS-Grenzen gibt, die sich auf hochvolumige Anwendungen auswirken können, insbesondere solche, die große Mengen ausgehenden Datenverkehrs wie E-Mail-Zustellsysteme bewältigen. Der A-Record sollte so konfiguriert werden, dass er auf den von uns erstellten ALB zeigt. Wenn Sie Route 53 zur Verwaltung der DNS-Einträge verwenden, können Sie direkt auf die ALB-Instanz verweisen, indem Sie „Alias“ aktivieren und den ALB auswählen; andernfalls, wenn Sie einen externen DNS-Anbieter verwenden, sollten Sie den A-Record auf die öffentliche IP-Adresse der ALB-Instanz zeigen lassen.
Ich empfehle die Verwendung eines Tools wie Postman, um zu testen, ob alles korrekt konfiguriert wurde, bevor Sie Ihr Bird-Webhook aktivieren. Sie können eine POST-Anfrage an Ihren Endpunkt senden und bestätigen, dass eine Antwort empfangen wird. Wenn Ihre POST-Anfrage keine Antwort zurückgibt, müssen Sie möglicherweise überprüfen, ob Ihr ALB auf den richtigen Port hört.
Erstellen Sie ein Bird Webhook
Nun sind wir bereit, das Webhook in Bird zu erstellen und den zuvor definierten Hostnamen des A-Records als unseren Zielendpunkt zu verwenden. Um das Webhook zu erstellen, navigieren Sie zum Webhooks-Bereich in Ihrem Bird-Konto und klicken auf „Webhook erstellen“. Sie werden aufgefordert, Ihrem Webhook einen Namen zu geben und eine Ziel-URL bereitzustellen – das Ziel sollte der Hostname des zuvor erstellten A-Records sein. Beachten Sie, dass die Ziel-URL möglicherweise „HTTPS://“ in der URL enthalten muss.
Sobald dies abgeschlossen ist, vergewissern Sie sich, dass das richtige Unterkonto und die richtigen Ereignisse ausgewählt sind, und drücken Sie „Webhook erstellen“, um Ihre Konfiguration zu speichern. Die Ereignisdaten für alle ausgewählten Ereignistypen werden nun an unsere Ziel-URL gestreamt und von unserem ALB für die Weiterverarbeitung konsumiert.
