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-Ereignis-Webhooks sind ein unglaublich wertvolles Werkzeug für Absender, um Daten automatisch an ihre Systeme zu übertragen. Dies kann die nachgelagerte Automatisierung vorantreiben, wie das Aktualisieren von Mailinglisten, das Auslösen automatisierter E-Mail-Reisen oder das Füllen interner Dashboards. Während dieselben Ereignisdaten über die Bird-Benutzeroberfläche mit Ereignissuche oder programmgesteuert durch Nutzung der Bird Events API abgerufen werden können, können Einschränkungen bei der Anzahl der in einer einzelnen Anfrage zurückgegebenen Datensätze oder Ratenbeschränkungen auf dem API-Endpunkt beide Methoden für große und komplexe Absender einschränkend machen.
Echtzeit-Ereignis-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 cron-Jobs planen zu müssen, die die Daten abrufen. Es gibt auch logistische Kompromisse, wenn die Daten abgerufen werden, anstatt sie sich zusenden zu lassen, wie zum Beispiel zu erkennen, welchen Zeitraum und welche Parameter man für jede API-Anfrage verwenden soll. Wenn die Zeiträume nicht perfekt ausgerichtet sind, riskieren Sie, Daten zu verpassen, und wenn die Zeiträume sich überschneiden, müssen Sie sich mit doppelten Datensätzen befassen. Mit Echtzeit-Webhooks werden Ereignisdaten einfach an Ihren Endpunkt gesendet, sobald sie innerhalb von Bird verfügbar sind.
Obwohl viele Absender die Vorteile der Echtzeit-Ereignisdaten zur Förderung nachgelagerter Automatisierungsprozesse sofort erkennen mögen, kann der tatsächliche Prozess zur Implementierung und Nutzung von Webhooks einschüchternd erscheinen. Dies kann besonders zutreffen, wenn Sie mit den technischen Komponenten zur Erstellung eines Endpunkts und der programmatischen Datenverarbeitung nicht vertraut sind. Es gibt Dienste, die Bird-Webhook-Daten konsumieren und automatisch in Ihre Datenbank ETL integrieren - 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 leicht selbst erstellen. Im Folgenden finden Sie eine einfache Anleitung, die Absendern hilft, sich bei der Erstellung eines Bird-Ereignis-Webhooks und der Nutzung der Daten mit der Infrastruktur innerhalb von AWS wohl zu fühlen.
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 diese 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 Diagramm auf hoher Ebene des beschriebenen Datenflusses ist unten zu sehen:
Um diesen Arbeitsablauf zu implementieren, bauen wir sie tatsächlich in umgekehrter Reihenfolge, beginnend mit dem Erstellen eines S3-Buckets, in dem wir unsere Ereignisdaten speichern, und arbeiten dann rückwärts – indem wir jede Komponente hinzufügen, die in das mündet, was wir gebaut haben.
Erstellen Sie einen S3 Bucket, um die Webhook-Daten zu speichern
Bevor wir unseren Load Balancer erstellen, um die Daten zu empfangen, oder unsere Lambda-Funktion, um die Daten zu speichern, müssen wir zuerst unseren S3-Bucket erstellen, in dem die Daten gespeichert werden. Dazu navigieren Sie zum S3-Service innerhalb von AWS und drücken „Bucket erstellen“. Sie werden aufgefordert, Ihrem Bucket einen Namen zuzuweisen und die Region festzulegen – achten Sie darauf, dieselbe Region wie Ihren ALB und die Lambda-Funktion zu verwenden. Wenn Ihr S3-Bucket erstellt wurde, ist er leer – wenn Sie die Daten in einem Ordner organisieren möchten, können Sie 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 weiter unten in unserer Lambda-Funktion referenziert.
Erstellen Sie eine Lambda-Funktion, um die Daten zu verarbeiten
Die tatsächliche Verarbeitung und Speicherung der Daten erfolgt durch eine Lambda-Funktion, die von unserem Application Load Balancer (ALB) aufgerufen wird.
Der erste Schritt besteht darin, Ihre Lambda-Funktion zu erstellen, indem Sie zur Lambda-Service innerhalb von AWS navigieren und auf „Funktion erstellen“ klicken. Sie werden aufgefordert, Ihrer Lambda-Funktion einen Namen zuzuweisen und die Programmiersprache auszuwählen, in der Sie Ihre Funktion schreiben möchten. Für dieses Beispiel verwenden wir Python als Laufzeitumgebung.
Jetzt müssen wir unsere Lambda-Funktion entwickeln. Nehmen wir für einen Moment an, dass unser Application Load Balancer konfiguriert wurde und die Webhook-Nutzlast an unsere Lambda-Funktion weiterleitet – die Lambda empfängt eine Nutzlast, die die vollständigen Header und den Body enthält. Die Nutzlast wird als Wörterbuch in unsere Lambda-Funktion über das Objekt „event“ übergeben. Sie können auf die Header und den Body der Nutzlast unabhängig zugreifen, indem Sie die Objekte „headers“ und „body“ innerhalb der Nutzlast referenzieren. In diesem Beispiel werden wir einfach den Header „x-messagesystems-batch-id“ lesen, wobei die Batch-ID ein von Bird für die Webhook-Batch erstellter eindeutiger Wert ist, und ihn als Dateinamen verwenden, wenn wir den Body als flache Datei in S3 speichern; Sie möchten jedoch möglicherweise zusätzliche Funktionen wie Authentifizierungsüberprüfungen oder Fehlerbehandlung hinzufügen, nach Bedarf.
Beim Speichern der Nutzlast in einer flachen Datei auf S3 müssen wir den Namen des S3-Buckets, den Ort und den Dateinamen der Datei definieren, in der die Nutzlastdaten gespeichert werden. In unserer Beispiel-Lambda-Funktion tun wir dies in der Funktion „store_batch“. In diesem Beispiel werden wir den gesamten 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 dafür, dass die Verbindung nicht auf der Übertragungsseite (in diesem Fall Bird) abläuft oder dass die Verbindung nicht beendet wird, bevor Ihre Lambda-Funktion die Ausführung abschließt. Es ist eine bewährte Praxis, Ihre Konsument-Funktion so effizient wie möglich zu gestalten und Datenverarbeitungsaktivitäten auf nachgeschaltete Prozesse zu beschränken – wie das Konvertieren der gebündelten, im JSON-Format vorliegenden 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 geringsten Privilegien durchzusetzen, daher empfehle ich, diese Berechtigungen nur für den S3-Bucket festzulegen, in dem die Webhook-Nutzlasten gespeichert werden.
Ein Beispiel unserer Konsument-Lambda-Funktion finden Sie hier.
Eine kurze Anmerkung zu der Batch-ID: Bird wird Ereignisse bündeln in einer einzigen Nutzlast, wobei jeder Batch 1 bis 350 oder mehr Ereignisprotokolle enthalten kann. Der Batch wird eine eindeutige Batch-ID erhalten, die verwendet werden kann, um den Batch-Status anzuzeigen, indem man die Event Webhooks API nutzt oder innerhalb Ihres Bird-Kontos durch Klicken auf einen Webhook-Stream und Auswahl von „Batch-Status“. Falls eine Webhook-Nutzlast nicht geliefert werden kann, z.B. bei einem Verbindungstimeout, wird Bird den Batch automatisch mit derselben Batch-ID erneut versuchen. Dies kann passieren, wenn Ihre Lambda-Funktion nahe an der maximalen Round-Trip-Zeit von 10 Sekunden läuft, was ein Grund ist, die Konsument-Funktion 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 im S3-Bucket erstellt wird – auf diese Weise erfolgt die Datenverarbeitung asynchron zur Übertragung der Daten, und es besteht kein Risiko, Daten aufgrund einer unterbrochenen Verbindung zu verlieren. Die Verarbeitungs-Lambda-Funktion bespreche ich in einem späteren Abschnitt.
Erstellen Sie ein Application Load Balancer
Um eine Webhook-Nutzlast zu empfangen, müssen wir einen Endpunkt bereitstellen, an den die Nutzlasten gesendet werden können. 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 – für diesen Fall möchten wir einen Application Load Balancer erstellen. Wir müssen einen Application Load Balancer (ALB) verwenden, um unseren Konsumenten zu erstellen, weil die Event-Webhooks als HTTP-Anfrage gesendet werden, und ALBs werden zum Routing von HTTP-Anfragen innerhalb von AWS verwendet. Wir könnten ein HTTP-Gateway als Alternative implementieren; allerdings verwenden wir für dieses Projekt ein ALB, weil es leichter und kostengünstiger ist als ein HTTP-Gateway. Es ist wichtig zu beachten, dass, wenn Sie sich entscheiden, ein HTTP-Gateway zu verwenden, das Ereignisformat anders sein kann als bei einem ALB und daher Ihre Lambda-Funktion das Anforderungsobjekt entsprechend behandeln muss.
Sobald Ihr ALB erstellt wurde, werden Sie aufgefordert, Ihrem ALB einen Namen zuzuweisen und das Schema sowie die Zugriffs-/Sicherheitseinstellungen zu konfigurieren – da wir planen, Ereignisdaten von einer externen Quelle (Bird) zu erhalten, möchten wir, dass unser ALB internet facing ist. Unter „Listener und Routing“ sollte der ALB auf HTTPS an Port 443 lauschen, und wir möchten eine Zielgruppe erstellen, die auf unsere Lambda-Funktion zeigt, sodass unser ALB eingehende Anfragen an die oben erstellte Konsum-Lambda-Funktion weiterleitet. Sie müssen auch sicherstellen, dass die Sicherheitsgruppe die Erlaubnis hat, Datenverkehr durch Port 443 zu akzeptieren.
Erstellen Sie einen DNS-Eintrag für den Load Balancer
Um es uns einfacher zu machen, unser ALB als Endpunkt zu verwenden, erstellen wir einen A-Record im DNS, der auf unser ALB zeigt. Dazu können wir den AWS Route 53-Service (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>). Der A-Record sollte so konfiguriert werden, dass er auf den von uns erstellten ALB zeigt. Wenn Sie Route 53 verwenden, um die DNS-Einträge zu verwalten, können Sie die ALB-Instanz direkt referenzieren, indem Sie „Alias“ aktivieren und die 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 ist, bevor Sie Ihr Bird-Webhook aktivieren. Sie können eine POST-Anfrage an Ihren Endpunkt stellen und bestätigen, dass eine Antwort eingegangen ist. 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 einen Bird Webhook
Jetzt sind wir bereit, den Webhook in Bird zu erstellen und den durch den A-Eintrag definierten Hostnamen als unseren Zielendpunkt zu verwenden. Um den Webhook zu erstellen, navigieren Sie zum Webhook-Bereich innerhalb Ihres Bird-Kontos 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://“ enthalten muss.
Nachdem Sie fertig sind, verifizieren Sie, dass das richtige Unterkonto und die 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 Downstream-Verarbeitung konsumiert.
