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 an ihre Systeme zu übermitteln. Dies kann die Automatisierung nachgelagerter Prozesse antreiben, wie z.B. das Aktualisieren von Verteilerlisten, das Auslösen automatisierter E-Mail-Kampagnen oder das Auffüllen interner Dashboards. Während auf dieselben Ereignisdaten über die Bird-UI mithilfe von Event Search zugegriffen werden kann, oder programmatisch durch Nutzung der Bird Events API, können Beschränkungen hinsichtlich der Anzahl der in einer einzelnen Anfrage zurückgegebenen Datensätze oder Ratengrenzen am API-Endpunkt beide dieser 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 übermittelt und die Daten konsumiert werden können, ohne dass Cron-Jobs geplant werden müssen, die die Daten abrufen. Es gibt auch logistische Kompromisse, wenn die Daten abgerufen werden, anstatt dass sie zu Ihnen gesendet werden, wie z.B. die Notwendigkeit, den genauen Zeitraum und die Parameter für jede API-Anfrage zu identifizieren. Wenn die Zeiträume nicht perfekt übereinstimmen, besteht das Risiko, Daten zu verpassen, und wenn sich die Zeiträume überschneiden, müssen doppelte Datensätze behandelt werden. 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 Automatisierung nachgelagerter Prozesse von vielen Absendern sofort verstanden werden können, kann der eigentliche Prozess der Implementierung und des Verbrauchs von Webhooks einschüchternd wirken. Dies kann besonders der Fall sein, wenn Sie mit den technischen Komponenten der Erstellung eines Endpunkts und der programmgesteuerten Verarbeitung der Daten nicht vertraut sind. Es gibt Dienste, die Bird-Webhook-Daten aufnehmen und automatisch in Ihre Datenbank ETL – ein Beispiel wäre StitchData, über das wir in der Vergangenheit gebloggt haben. Wenn Sie jedoch mehr Kontrolle über den Prozess haben möchten, können Sie die Komponenten problemlos selbst erstellen. Das Folgende ist ein einfacher Leitfaden, der Absendern hilft, sich beim Erstellen eines Bird-Ereignis-Webhooks und beim Konsumieren 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 diese Ereignisdaten in Echtzeit zu einem 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 hochrangiges Diagramm des beschriebenen Datenflusses ist unten zu sehen:
Um diesen Workflow umzusetzen, lassen Sie uns tatsächlich in umgekehrter Reihenfolge vorgehen, beginnend mit der Erstellung eines S3-Buckets zur Speicherung unserer Ereignisdaten, und dann rückwärts arbeiten – indem wir jede Komponente hinzufügen, die in das, was wir gebaut haben, einspeist.
Erstellen Sie einen S3-Bucket zur Speicherung 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. Um dies zu tun, navigieren Sie zum S3-Dienst innerhalb von AWS und drücken Sie „Bucket erstellen“. Sie werden aufgefordert, Ihrem Bucket einen Namen zuzuweisen und die Region festzulegen – stellen Sie sicher, dass Sie dieselbe Region wie Ihr ALB und Ihre Lambda-Funktion verwenden. Wenn Ihr S3-Bucket erstellt wurde, ist er leer – wenn Sie die Daten in einem Ordner organisieren möchten, können Sie entweder jetzt das beabsichtigte Verzeichnis erstellen, oder das Verzeichnis wird erstellt, wenn Ihre Lambda-Funktion die Datei speichert. In diesem Beispiel nannten wir unseren S3-Bucket „bird-webhooks“ und erstellten einen Ordner namens „B Event Data“, um unsere Ereignisdaten zu speichern – Sie werden diese Namen in unserer Lambda-Funktion unten sehen.
Erstellen Sie eine Lambda-Funktion zur Nutzung der Daten
Die eigentliche Verarbeitung und Speicherung der Daten erfolgt durch eine Lambda-Funktion, die von unserem Anwendungs-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 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 Anwendungs-Load-Balancer konfiguriert wurde und die Webhook-Nutzlast an unsere Lambda-Funktion weiterleitet – die Lambda-Funktion erhält eine Nutzlast, die die vollständigen Header und den Body enthält. Die Nutzlast wird als Wörterbuch in unsere Lambda-Funktion unter Verwendung des Objekts „event“ übergeben. Sie können auf die Header und den Body der Nutzlast unabhängig durch Zugriff auf die „headers“- und „body“-Objekte innerhalb der Nutzlast verweisen. In diesem Beispiel werden wir einfach den „x-messagesystems-batch-id“-Header lesen, wobei die Batch-ID ein eindeutiger Wert ist, der von Bird für den Webhook-Batch erstellt wird, und ihn als Dateinamen verwenden, wenn der Body als Flachdatei in S3 gespeichert wird; Sie möchten jedoch möglicherweise zusätzliche Funktionen hinzufügen, wie z. B. Authentifizierungsprüfungen oder Fehlerbehandlung, nach Bedarf.
Beim Speichern der Nutzlast als Flachdatei auf S3 müssen wir den Namen des S3-Buckets, den Speicherort und den Dateinamen der Datei festlegen, in der die Nutzlastdaten gespeichert werden sollen. In unserer Beispiel-Lambda-Funktion tun wir dies innerhalb der Funktion „store_batch“. In diesem Beispiel speichern wir den gesamten Batch als einzelne Datei, 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 Timeout-Einstellungen der Verbindung an Ihrem Load Balancer anpassen könnten, gibt es keine Garantien, 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 beendet. Es ist eine bewährte Praxis, Ihre Konsumfunktion so effizient wie möglich zu gestalten und Datenverarbeitungsaktivitäten nach Möglichkeit für nachgelagerte Prozesse vorzuhalten – z. B. 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 die Berechtigungen PutObject und GetObject für S3. Es ist eine bewährte Praxis, das Prinzip der geringsten Rechte durchzusetzen, daher empfehle ich, diese Berechtigungen nur für den S3-Bucket festzulegen, in dem die Webhook-Nutzlasten gespeichert werden.
Ein Beispiel unserer Konsum-Lambda-Funktion finden Sie hier.
Eine kurze Anmerkung zur Batch-ID: Bird wird Ereignisse bündeln in einer einzigen Nutzlast, wobei jeder Batch 1 bis 350 oder mehr Ereignisdatensätze enthalten kann. Dem Batch wird eine eindeutige Batch-ID zugewiesen, die zum Anzeigen des Batch-Status durch Nutzung der Event Webhooks API oder innerhalb Ihres Bird-Kontos durch Klicken auf einen Webhook-Stream und Auswahl von „Batch Status“ verwendet werden kann. Falls eine Webhook-Nutzlast nicht zugestellt werden konnte, wie z. B. bei einem Verbindungsabbruch, wird Bird automatisch den Batch mit derselben Batch-ID erneut senden. Dies kann passieren, wenn Ihre Lambda-Funktion nahe an der maximalen Round-Trip-Zeit von 10 Sekunden läuft und ist ein Grund dafür, die Konsumfunktion zu optimieren, um die Ausführungszeit zu reduzieren.
Um alle Datenverarbeitungsaktivitäten zu übernehmen, empfehle ich, eine separate Lambda-Funktion zu erstellen, die jedes Mal ausgeführt wird, wenn auf dem S3-Bucket eine neue Datei erstellt wird – auf diese Weise wird die Datenverarbeitung asynchron zur Übertragung der Daten durchgeführt, und es besteht keine Gefahr, dass Daten aufgrund einer unterbrochenen Verbindung verloren gehen. Ich bespreche die Verarbeitungslambda-Funktion in einem späteren Abschnitt.
Erstellen Sie einen Anwendungs-Load-Balancer
Um eine Webhook-Nutzlast zu empfangen, müssen wir einen Endpunkt bereitstellen, an den die Nutzlasten gesendet werden sollen. Dies tun wir, indem wir innerhalb von AWS einen Anwendungs-Load-Balancer 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 Anwendungs-Load-Balancer erstellen. Wir müssen einen Anwendungs-Load-Balancer (ALB) verwenden, um unseren Verbraucher zu erstellen, da die Ereignis-Webhooks als HTTP-Anforderung gesendet werden, und ALBs werden zum Routing von HTTP-Anfragen innerhalb von AWS verwendet. Wir könnten ein HTTP-Gateway als Alternative implementieren; jedoch verwenden wir ein ALB für dieses Projekt, da es leichter und kostengünstiger als ein HTTP-Gateway ist. Es ist wichtig zu beachten, dass, wenn Sie sich für die Verwendung eines HTTP-Gateways entscheiden, das Ereignisformat möglicherweise anders als bei einem ALB ist, 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 und die Zugriffs-/Sicherheitseinstellungen zu konfigurieren – da wir vorhaben, Ereignisdaten aus einer externen Quelle (Bird) zu empfangen, möchten wir, dass unser ALB internetorientiert ist. Unter „Hörer und Routing“ sollte das ALB auf HTTPS an Port 443 hören, und wir möchten eine Zielgruppe erstellen, die auf unsere Lambda-Funktion zeigt, damit unser ALB eingehende Anfragen an die Konsum-Lambda-Funktion weiterleitet, die wir oben erstellt haben. Außerdem müssen Sie sicherstellen, dass die Sicherheitsgruppe die Berechtigung hat, Datenverkehr durch Port 443 zu akzeptieren.
Erstellen Sie einen DNS-Eintrag für den Load Balancer
Um die Nutzung unseres ALB als Endpunkt zu erleichtern, erstellen wir einen A-Eintrag im DNS, der auf unser ALB zeigt. Dafür können wir den AWS Route 53-Dienst (oder Ihren aktuellen DNS-Anbieter) verwenden und einen A-Eintrag für den Hostnamen erstellen, den Sie für Ihren Endpunkt verwenden möchten (z. B. spevents.<your_domain>). Der A-Eintrag sollte so konfiguriert werden, dass er auf das von uns erstellte ALB zeigt. Wenn Sie Route 53 verwenden, um die DNS-Einträge zu verwalten, können Sie auf die ALB-Instanz direkt verweisen, indem Sie „Alias“ aktivieren und das ALB auswählen; andernfalls, wenn Sie einen externen DNS-Anbieter verwenden, sollten Sie den A-Eintrag auf die öffentliche IP-Adresse der ALB-Instanz richten.
Ich empfehle, ein Tool wie Postman zu verwenden, um zu testen, ob alles korrekt konfiguriert wurde, bevor Sie Ihren 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 einen Bird-Webhook
Jetzt sind wir bereit, den Webhook in Bird zu erstellen und den durch den A-Eintrag definierten Hostnamen als unser Zielendpunkt zu verwenden. Um den Webhook zu erstellen, navigieren Sie zum Webhook-Bereich in Ihrem Bird-Konto und klicken Sie auf „Webhook erstellen“. Sie werden aufgefordert, Ihrem Webhook einen Namen zuzuweisen und eine Ziel-URL anzugeben – das Ziel sollte der Hostname des zuvor erstellten A-Eintrags sein. Beachten Sie, dass die Ziel-URL möglicherweise „HTTPS://“ in der URL beinhalten muss.
Nach Abschluss überprüfen Sie, ob 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 zu unserer Ziel-URL gestreamt und von unserem ALB für die nachgelagerte Verarbeitung konsumiert.
