De volgende is een eenvoudige gids om afzenders te helpen zich op hun gemak te voelen bij het creëren van een Bird-evenementwebhook en het gebruiken van de gegevens met behulp van de infrastructuur binnen AWS.
Bird’s realtime event webhooks zijn een ongelooflijk waardevol hulpmiddel voor verzenders om automatisch gegevens naar hun systemen te laten pushen. Dit kan downstream automatisering aandrijven, zoals het bijwerken van mailinglijsten, het activeren van geautomatiseerde e-mailtrajecten of het vullen van interne dashboards. Hoewel dezelfde gebeurtenisgegevens toegankelijk zijn via de Bird UI met behulp van Event Search, of programmeerbaar door gebruik te maken van de Bird Events API, kunnen beperkingen op het aantal records dat wordt teruggegeven in één verzoek of snelheidsbeperkingen op het API-eindpunt beide methoden beperkend maken voor grote en geavanceerde verzenders.
Realtime event webhooks stellen een verzender in staat een eindpunt te configureren waarnaar Bird de gegevens verzendt, en de gegevens kunnen worden verwerkt zonder dat cron-jobs nodig zijn die de gegevens ophalen. Er zijn ook logistieke afwegingen bij het ophalen versus het pushen van de gegevens, zoals het identificeren van welk tijdsbestek en welke parameters moeten worden gebruikt voor elk API-verzoek. Als de tijdsperiodes niet perfect op elkaar zijn afgestemd, loop je het risico gegevens te missen, en als de tijdsperiodes overlappen, moet je dubbele gegevensrecords verwerken. Met realtime webhooks worden gebeurtenisgegevens simpelweg naar je eindpunt gepusht zodra ze beschikbaar zijn binnen Bird.
Hoewel de voordelen van het ontvangen van gebeurtenisgegevens in realtime om downstream automatiseringsprocessen aan te sturen door veel verzenders onmiddellijk begrepen kunnen worden, kan het daadwerkelijke proces om webhooks te implementeren en te verwerken ontmoedigend zijn. Dit kan vooral het geval zijn als je niet bekend bent met de technische componenten van het maken van een eindpunt en het programmatisch verwerken van de gegevens. Er zijn services beschikbaar die Bird webhook-gegevens verbruiken en ETL in je database automatisch – een voorbeeld zou StitchData zijn, waarover we in het verleden hebben geblogd. Echter, als je meer controle wilt hebben over het proces, kun je de componenten eenvoudig zelf bouwen. Het volgende is een eenvoudige gids om verzenders comfortabel te laten voelen bij het maken van een Bird events webhook en het verwerken van de gegevens met behulp van de infrastructuur binnen AWS.
Configureren van de Webhook Target Endpoint
Wanneer een Bird-evenement wordt aangemaakt, willen we dat die gegevens in real-time naar een eindpunt in AWS worden gestreamd, zodat we die gegevens programmatisch kunnen gebruiken en consumeren. De gegevens worden van Bird naar een doel-eindpunt gestuurd, dat de payload doorstuurt naar een lambda-functie die de gegevens verwerkt en opslaat in een S3-bucket. Een diagram op hoog niveau van de beschreven gegevensstroom is hieronder te zien:
Om deze workflow te implementeren, laten we ze daadwerkelijk in omgekeerde volgorde bouwen, te beginnen met het maken van een S3-bucket waar we onze evenementgegevens opslaan en dan achteruit werken – waarbij we elke component toevoegen die deel uitmaakt van wat we hebben gebouwd.
Maak een S3-bucket om de Webhook-gegevens op te slaan
Voordat we onze load balancer maken om de gegevens te accepteren, of onze lambda-functie om de gegevens op te slaan, moeten we eerst onze S3-bucket maken waar de gegevens worden opgeslagen. Om dit te doen, navigeer naar de S3-service binnen AWS en druk op “Bucket maken.” U wordt gevraagd om een naam aan uw bucket toe te wijzen en de regio in te stellen – zorg ervoor dat u dezelfde regio gebruikt als uw ALB en lambda-functie. Wanneer uw S3-bucket is aangemaakt, zal deze leeg zijn – als u de gegevens in een map wilt organiseren, kunt u de beoogde directory nu maken, of de directory wordt aangemaakt wanneer uw lambda-functie het bestand opslaat. In dit voorbeeld noemden we onze S3-bucket “bird-webhooks” en maakten we een map genaamd “B Event Data” om onze evenementgegevens op te slaan – u zult deze namen zien terugkomen in onze lambda-functie hieronder.
Maak een Lambda-functie om de gegevens te consumeren
De eigenlijke verwerking en opslag van de gegevens wordt uitgevoerd door een lambda-functie die door onze application load balancer (ALB) wordt aangeroepen.
De eerste stap is om uw lambda-functie te maken door naar de Lambda-service binnen AWS te navigeren en op “Functie maken” te klikken. U wordt gevraagd om een naam aan uw lambda-functie toe te wijzen en te selecteren in welke programmeertaal u uw functie wilt schrijven. Voor dit voorbeeld gebruiken we Python als runtime-taal.
Nu moeten we onze lambda-functie ontwikkelen. Laten we voor een moment aannemen dat onze application load balancer is geconfigureerd en de webhook-payload naar onze lambda-functie doorstuurt – de lambda ontvangt een payload met de volledige headers en body. De payload wordt aan onze lambda-functie doorgegeven met behulp van het object “event” als een dictionary. U kunt afzonderlijk verwijzen naar de headers en de body van de payload door toegang te krijgen tot de “headers” en “body” objecten binnen de payload. In dit voorbeeld gaan we simpelweg de header “x-messagesystems-batch-id” lezen, waar de batch-ID een unieke waarde is die door Bird is aangemaakt voor de webhook-batch, en deze als bestandsnaam gebruiken bij het opslaan van de body als een plat bestand in S3; u kunt echter extra functionaliteit toevoegen, zoals authenticatiecontroles of foutherstel, indien nodig.
Bij het opslaan van de payload naar een plat bestand op S3, moeten we de naam van de S3-bucket, locatie en bestandsnaam van het bestand waar de payloadgegevens worden opgeslagen definiëren. In onze voorbeeld lambda-functie doen we dit binnen de functie “store_batch”. In dit voorbeeld gaan we de gehele batch als een enkel bestand opslaan, wat helpt om ervoor te zorgen dat de gegevens zijn verzameld en opgeslagen voordat de HTTP-verbinding tussen Bird en uw eindpunt verloopt. Terwijl u de instelling voor time-out van de verbinding op uw load balancer kunt aanpassen, zijn er geen garanties dat de verbinding niet zal verlopen aan de zendkant (in dit geval Bird) of dat de verbinding niet zal worden verbroken voordat uw lambda-functie klaar is met uitvoeren. Het is een goede gewoonte om uw consumentfunctie zo efficiënt mogelijk te houden en gegevensverwerkingsactiviteiten te reserveren voor neerwaartse processen waar mogelijk – zoals het converteren van de batch JSON-geformatteerde payload naar een CSV-bestand of het laden van de evenementgegevens in een database.
Het is belangrijk op te merken dat u mogelijk de machtigingen voor uw lambda-functie moet bijwerken. Uw uitvoeringsrol zal PutObject en GetObject-machtigingen voor S3 nodig hebben. Het is een beste praktijk om het principe van minste privilege te handhaven, dus ik raad aan deze machtigingen alleen in te stellen voor de S3-bucket waar de webhook-payloads worden opgeslagen.
Een voorbeeld van onze consument-lambda-functie is hier te vinden.
Een korte opmerking over de batch-ID: Bird zal evenementen verzamelen in één enkele payload, waarbij elke batch 1 tot 350 of meer gebeurtenisrecords kan bevatten. De batch krijgt een unieke batch-ID, die kan worden gebruikt om de batchstatus te bekijken door gebruik te maken van de Event Webhooks API of binnen uw Bird-account door op een webhookstroom te klikken en “Batchstatus” te selecteren. In het geval dat een webhook-payload niet kon worden afgeleverd, bijvoorbeeld bij een verbindingstijdoverschrijding, zal Bird automatisch de batch opnieuw proberen met dezelfde batch-ID. Dit kan gebeuren wanneer uw lambda-functie dicht in de buurt komt van de maximale rondreisduur van 10 seconden en is een reden om de consumentfunctie te optimaliseren om de uitvoeringstijd te verkorten.
Om alle gegevensverwerkingsactiviteiten te behandelen, raad ik aan een aparte lambda-functie te maken die wordt uitgevoerd telkens wanneer een nieuw bestand op de S3-bucket wordt aangemaakt – op deze manier worden de gegevensverwerkingen asynchroon uitgevoerd aan de verzending van de gegevens, en is er geen risico op gegevensverlies door een verbroken verbinding. Ik bespreek de verwerking van de lambda-functie in een later gedeelte.
Maak een Application Load Balancer
Om een webhook-payload te ontvangen, moeten we een eindpunt bieden om de payloads naar te sturen. We doen dit door een application load balancer in AWS te maken door te navigeren naar EC2 > Load Balancers en op “Load Balancer maken” te klikken. U wordt gevraagd welk type load balancer u wilt maken – hiervoor willen we een application load balancer maken. We moeten een application load balancer (ALB) gebruiken om onze consument te bouwen omdat de event webhooks worden verzonden als een HTTP-verzoek, en ALB’s worden gebruikt voor het routeren van HTTP-verzoeken binnen AWS. We zouden een HTTP Gateway als alternatief kunnen implementeren; we gebruiken echter een ALB voor dit project omdat het lichter en kosteneffectiever is dan HTTP Gateway. Het is belangrijk op te merken dat als u ervoor kiest om een HTTP Gateway te gebruiken, het gebeurtenisformaat mogelijk anders is dan met een ALB, en daarom moet uw lambda-functie met het verzoekobject omgaan.
Zodra uw ALB is aangemaakt, wordt u gevraagd om een naam toe te wijzen aan uw ALB en de schema- en toegangs/beveiligingsinstellingen te configureren – aangezien we van plan zijn evenementgegevens van een externe bron (Bird) te ontvangen, willen we dat onze ALB internet-facing is. Onder “Listeners en routing” moet de ALB luisteren naar HTTPS op poort 443, en willen we een Target group maken die wijst naar onze lambda-functie, zodat onze ALB inkomende verzoeken doorstuurt naar de hieronder gemaakte consume lambda-functie. U moet er ook voor zorgen dat de beveiligingsgroep toestemming heeft om verkeer via poort 443 te accepteren.
Maak een DNS-record voor de Load Balancer
Om het voor ons gemakkelijker te maken om onze ALB als eindpunt te gebruiken, maken we een A-record in DNS dat naar onze ALB verwijst. Hiervoor kunnen we de AWS Route 53-service (of uw huidige DNS-provider) gebruiken en een A-record maken voor de hostnaam die u wilt gebruiken voor uw eindpunt (bijv. spevents.<uw_domein>). Het A-record moet worden geconfigureerd om naar de ALB te verwijzen die we hebben gemaakt. Als u Route 53 gebruikt om uw DNS-records te beheren, kunt u de ALB-instantie rechtstreeks aanspreken door “Alias” in te schakelen en de ALB te selecteren; anders, als u een externe DNS-provider gebruikt, zou u het A-record moeten laten wijzen naar het openbare IP-adres van de ALB-instantie.
Ik raad aan om een tool zoals Postman te gebruiken om te testen of alles correct is geconfigureerd voordat u uw Bird-webhook inschakelt. U kunt een POST-verzoek naar uw eindpunt sturen en bevestigen dat er een reactie wordt ontvangen. Als uw POST-verzoek geen reactie retourneert, moet u misschien dubbel controleren of uw ALB naar de juiste poort luistert.
Maak een Bird Webhook
Nu zijn we klaar om de webhook in Bird aan te maken en de hostnaam te gebruiken die door het A-record hierboven is gedefinieerd als ons doeleindpunt. Om de webhook te maken, navigeer naar de sectie Webhooks binnen uw Bird-account en klik op “Webhook maken.” U wordt gevraagd om een naam voor uw webhook toe te wijzen en een doel-URL op te geven – het doel moet de hostnaam zijn van het A-record dat u eerder hebt gemaakt. Merk op dat de doel-URL mogelijk “HTTPS://” vereist in de URL.
Nadat dit is voltooid, verifieer of het juiste subaccount en de gebeurtenissen zijn geselecteerd, en druk op “Webhook maken” om uw configuratie op te slaan. De gebeurtenisgegevens voor alle geselecteerde gebeurtenistypen zullen nu naar onze doel-URL stromen en door onze ALB voor downstreamverwerking worden geconsumeerd.
