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 real-time event webhooks zijn een ongelooflijk waardevol hulpmiddel voor verzenders om gegevens automatisch naar hun systemen te laten pushen. Dit kan downstream-automatisering aandrijven, zoals het bijwerken van mailinglijsten, het activeren van geautomatiseerde e-mailreizen of het vullen van interne dashboards. Hoewel dezelfde gebeurtenisgegevens toegankelijk zijn via de Bird UI met Event Search of programmeerbaar door gebruik te maken van de Bird Events API, kunnen beperkingen op het aantal records dat in één verzoek wordt geretourneerd of snelheidslimieten op het API-eindpunt beide methoden restrictief maken voor grote en geavanceerde verzenders.
Real-time event webhooks stellen een verzender in staat om een eindpunt te configureren waar Bird de gegevens naar verzendt, en de gegevens kunnen worden verwerkt zonder cron-jobs in te plannen die de gegevens ophalen. Er zijn ook logistieke afwegingen bij het ophalen van de gegevens in plaats van deze naar u te laten pushen, zoals het identificeren van welke tijdsperiode en parameters voor elk API-verzoek moeten worden gebruikt. Als de tijdsperioden niet perfect zijn uitgelijnd, riskeert u gegevens te missen, en als de tijdsperioden overlappen, moet u dubbele gegevensrecords verwerken. Met real-time webhooks worden gegevens van gebeurtenissen eenvoudig naar uw eindpunt gepusht zodra deze binnen Bird beschikbaar komen.
Hoewel de voordelen van het ontvangen van gebeurtenisgegevens in real-time om downstream-automatiseringsprocessen aan te drijven voor veel verzenders onmiddellijk begrijpelijk kunnen zijn, kan het daadwerkelijke proces voor het implementeren en verwerken van webhooks intimiderend zijn. Dit kan vooral gelden als u onbekend bent met de technische componenten voor het maken van een eindpunt en het programmatisch verwerken van de gegevens. Er zijn diensten beschikbaar die Bird-webhookgegevens verbruiken en automatisch ETL in uw database - een voorbeeld zou StitchData zijn, waarover we in het verleden hebben geblogd. Als u echter meer controle over het proces wilt, kunt u de componenten gemakkelijk zelf bouwen. Het volgende is een eenvoudige gids om verzenders op hun gemak 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 evenementgegevens in realtime naar een eindpunt in AWS worden gestreamd, zodat we die gegevens programmatisch kunnen gebruiken en verwerken. 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, gaan we deze omgekeerd opbouwen, te beginnen met het creëren van een S3-bucket waar we onze evenementgegevens zullen opslaan en vervolgens achteruit werken - elk onderdeel dat in wat we hebben opgebouwd toevoegd.
Maak een S3 Bucket om de Webhook Data 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. Hoewel S3 uitstekende opslag biedt voor webhook-gegevens, moeten organisaties die ook PostgreSQL-databases voor evenementverwerking gebruiken, passende backup- en herstelprocedures implementeren om hun gestructureerde gegevens te beschermen naast hun S3-opslagstrategie. Om dit te doen, navigeert u naar de S3-service binnen AWS en drukt u op 'Create Bucket'. U wordt gevraagd om een naam toe te wijzen aan uw bucket en de regio in te stellen - zorg ervoor dat u dezelfde regio gebruikt als uw ALB en lambda-functie. Wanneer uw S3-bucket is gemaakt, is deze leeg - als u de gegevens binnen een map wilt organiseren, kunt u nu de bedoelde directory maken, of de directory wordt gemaakt wanneer uw lambda-functie het bestand opslaat. In dit voorbeeld hebben we onze S3-bucket 'bird-webhooks' genoemd en een map genaamd 'B Event Data' gemaakt 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 Verbruiken
De daadwerkelijke verwerking en opslag van de gegevens wordt uitgevoerd door een lambda-functie die wordt opgeroepen door onze application load balancer (ALB).
De eerste stap is om uw lambda-functie te maken door naar de Lambda-service binnen AWS te navigeren en op 'Create Function' te klikken. U wordt gevraagd een naam toe te wijzen aan uw lambda-functie en te selecteren in welke programmeertaal u uw functie wilt schrijven. Voor dit voorbeeld gebruiken we Python als de runtime taal.
Nu moeten we onze lambda-functie ontwikkelen. Laten we er even vanuit gaan dat onze application load balancer is geconfigureerd en de webhook-payload doorstuurt naar onze lambda-functie - de lambda ontvangt een payload inclusief de volledige headers en body. De payload wordt in onze lambda-functie doorgegeven met behulp van het object 'event' als een dictionary. U kunt de headers en de body van de payload onafhankelijk benaderen door de 'headers' en 'body' objecten binnen de payload te benaderen. In dit voorbeeld gaan we simpelweg de 'x-messagesystems-batch-id' header lezen, waar de batch-ID een unieke waarde is die door Bird voor de webhook-batch is gecreëerd, en deze gebruiken als de bestandsnaam wanneer de body als een flat-file in S3 wordt opgeslagen; u wilt echter mogelijk extra functionaliteit toevoegen zoals authenticatiecontroles of foutafhandeling, indien nodig.
Bij het opslaan van de payload naar een flat-file in 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 'store_batch' functie. In dit voorbeeld gaan we de hele batch opslaan als een enkel bestand, wat helpt ervoor te zorgen dat de gegevens worden verzameld en opgeslagen voordat de HTTP-verbinding tussen Bird en uw eindpunt wordt verbroken. Hoewel u de time-outinstellingen van de verbinding op uw load balancer zou kunnen aanpassen, zijn er geen garanties dat de verbinding niet aan de verzendzijde (in dit geval Bird) verloopt of dat de verbinding niet wordt beëindigd voordat uw lambda-functie klaar is met uitvoeren. Het is een beste praktijk om uw consumer-functie zo efficiënt mogelijk te houden en gegevensverwerkingsactiviteiten te reserveren voor downstream-processen waar mogelijk - zoals het converteren van de gebatchte 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 heeft PutObject- en GetObject-machtigingen voor S3 nodig. Het is een beste praktijk om het principe van het minste privilege te handhaven, dus ik raad aan deze machtigingen in te stellen voor alleen de S3-bucket waar de webhook-payloads worden opgeslagen.
Een voorbeeld van onze consumer lambda-functie is te vinden hier.
Als een korte opmerking over de batch-ID: Bird zal evenementen groeperen in een 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 te klikken op een webhook stroom en 'Batch Status' te selecteren. In het geval dat een webhook-payload niet kon worden afgeleverd, zoals bij een connection timeout, zal Bird automatisch de batch opnieuw proberen met dezelfde batch-ID. Dit kan gebeuren wanneer uw lambda-functie dicht bij de maximale round-trip tijd van 10 seconden draait en is een reden om de consumer-functie te optimaliseren om de uitvoeringstijd te verkorten.
Om alle gegevensverwerkingsactiviteiten af te handelen, raad ik aan een aparte lambda-functie te maken die wordt uitgevoerd telkens wanneer een nieuw bestand in de S3-bucket wordt aangemaakt - op deze manier wordt de gegevensverwerking asynchroon uitgevoerd aan de gegevensoverdracht, en is er geen risico op gegevensverlies door een beëindigde verbinding. Ik bespreek de verwerkings lambda-functie in een latere sectie.
Maak een Application Load Balancer
Om een webhook-payload te ontvangen, moeten we een eindpunt bieden om de payloads naar toe te sturen. We doen dit door een application load balancer binnen AWS te maken door te navigeren naar EC2 > Load Balancers en op 'Create Load Balancer' te klikken. U wordt gevraagd om te kiezen 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 evenementen-webhooks worden verzonden als een HTTP-verzoek, en ALB's worden gebruikt voor het routeren van HTTP-verzoeken binnen AWS. We zouden als alternatief een HTTP Gateway 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 een HTTP Gateway kiest, het evenementformaat anders kan zijn dan bij een ALB, en daarom moet uw lambda-functie het aanvraagobject dienovereenkomstig afhandelen.
Zodra uw ALB is gemaakt, wordt u gevraagd een naam toe te wijzen aan uw ALB en het schema en de toegang-/beveiligingsinstellingen te configureren - aangezien we van plan zijn om gegevens van een externe bron (Bird) te ontvangen, willen we dat onze ALB internet-facing is. Onder 'Listeners and routing', moet de ALB luisteren naar HTTPS op poort 443, en we willen een Target-groep aanmaken die wijst naar onze lambda-functie, zodat onze ALB inkomende verzoeken doorstuurt naar de consume lambda-functie die we hierboven hebben gemaakt. 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 onze ALB als een eindpunt te gebruiken, maken we een A-record in DNS dat wijst naar onze ALB. 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.<your_domain>). Wanneer u werkt met DNS op schaal op AWS, houd er rekening mee dat er ongedocumenteerde DNS-limieten zijn die van invloed kunnen zijn op toepassingen met een hoog volume, vooral die welke grote hoeveelheden uitgaand verkeer verwerken zoals e-mailafleveringssystemen. Het A-record moet zo worden geconfigureerd dat het naar de door ons gemaakte ALB wijst. Als u Route 53 gebruikt voor het beheren van de DNS-records, kunt u de ALB-instantie direct refereren door 'Alias' in te schakelen en de ALB te selecteren; anders, als u een externe DNS-provider gebruikt, moet u het A-record laten wijzen naar het openbare IP-adres van de ALB-instantie.
Ik raad aan 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 doen en bevestigen dat 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 te maken en de hostnaam te gebruiken die is gedefinieerd door het A-record hierboven als ons doeleindpunt. Om de webhook te maken, navigeert u naar het Webhooks-gedeelte binnen uw Bird-account en klikt u op 'Create Webhook'. U wordt gevraagd een naam toe te wijzen aan uw webhook en een doel-URL op te geven - het doel moet de hostnaam zijn van het eerder gemaakte A-record. Merk op dat de doel-URL mogelijk vereist dat 'HTTPS://' in de URL is opgenomen.
Nadat u klaar bent, controleert u of het juiste subaccount en de juiste evenementen zijn geselecteerd en drukt u op 'Create Webhook' om uw configuratie op te slaan. De evenementgegevens voor alle geselecteerde evenemententypen zullen nu naar onze doel-URL stromen en worden opgeconsumeerd door onze ALB voor downstream-verwerking.
