Le guide suivant est une simple aide pour permettre aux expéditeurs de se sentir à l'aise lors de la création d'un webhook d'événements Bird et de l'utilisation des données via l'infrastructure d'AWS.
Les webhooks d'événements en temps réel de Bird sont un outil incroyablement précieux pour permettre aux expéditeurs d'avoir des données automatiquement envoyées à leurs systèmes. Cela peut entraîner une automatisation en aval telle que la mise à jour des listes de diffusion, le déclenchement de parcours d'email automatisés ou l'alimentation de tableaux de bord internes. Bien que les mêmes données d'événements puissent être accessibles via l'interface utilisateur de Bird en utilisant la recherche d'événements, ou de manière programmatique en utilisant l'API Events de Bird, les limitations du nombre d'enregistrements renvoyés dans une seule requête ou les limites de taux imposées sur le point de terminaison de l'API peuvent rendre ces deux méthodes restrictives pour les expéditeurs importants et sophistiqués.
Les webhooks d'événements en temps réel permettent à un expéditeur de configurer un point de terminaison où Bird transmet les données, et les données peuvent être consommées sans avoir à planifier des tâches cron pour extraire les données. Il y a aussi des compromis logistiques lors de l'extraction des données par opposition au fait de recevoir les données, comme devoir identifier la période et les paramètres à utiliser pour chaque requête API. Si les périodes ne sont pas parfaitement alignées, vous risquez de manquer des données, et si les périodes se chevauchent, vous devez gérer les enregistrements de données en double. Avec les webhooks en temps réel, les données d'événements sont simplement envoyées à votre point de terminaison dès qu'elles sont disponibles dans Bird.
Alors que les avantages de recevoir des données d'événements en temps réel pour stimuler les processus d'automatisation en aval peuvent être immédiatement compris par de nombreux expéditeurs, le processus réel de mise en œuvre et de consommation des webhooks peut être intimidant. Cela peut être particulièrement vrai si vous ne connaissez pas les composants techniques pour créer un point de terminaison et gérer les données de manière programmatique. Il existe des services disponibles qui consommeront les données de webhooks de Bird et les intégreront automatiquement dans votre base de données via ETL – un exemple serait StitchData, dont nous avons parlé dans un de nos blogs. Cependant, si vous souhaitez avoir plus de contrôle sur le processus, vous pouvez facilement construire les composants vous-même. Voici un guide simple pour aider les expéditeurs à se sentir à l'aise lors de la création d'un webhook d'événements Bird et de la consommation des données en utilisant l'infrastructure au sein d'AWS.
Configuration de l'Endpoint de Cible Webhook
Lorsqu'un événement Bird est créé, nous voulons que les données de cet événement soient diffusées en temps réel à un point de terminaison dans AWS afin que nous puissions consommer et utiliser ces données de manière programmée. Les données seront envoyées de Bird à un point de terminaison cible, qui transmettra la charge utile à une fonction lambda qui traitera et stockera les données dans un bucket S3. Un schéma de haut niveau du flux de données décrit peut être vu ci-dessous :
Pour mettre en œuvre ce workflow, construisons-les en réalité dans l'ordre inverse en commençant par créer un bucket S3 où nous stockerons nos données d'événement et ensuite, travailler à rebours – en ajoutant chaque composant qui alimente ce que nous avons construit.
Créer un bucket S3 pour stocker les données du Webhook
Avant de créer notre équilibreur de charge pour accepter les données, ou notre fonction lambda pour stocker les données, nous devons d'abord créer notre bucket S3 où les données seront stockées. Pour ce faire, accédez au service S3 dans AWS et appuyez sur « Create Bucket ». Vous serez invité à attribuer un nom à votre bucket et à définir la région - assurez-vous d'utiliser la même région que votre ALB et votre fonction lambda. Lorsque votre bucket S3 est créé, il sera vide - si vous souhaitez organiser les données à l'intérieur d'un dossier, vous pouvez soit créer le répertoire souhaité maintenant, soit le répertoire sera créé lorsque votre fonction lambda stockera le fichier. Dans cet exemple, nous avons nommé notre bucket S3 « bird-webhooks » et créé un dossier nommé « B Event Data » pour stocker nos données d'événement - vous verrez ces noms référencés dans notre fonction lambda ci-dessous.
Créer une fonction Lambda pour consommer les données
Le traitement et le stockage réels des données seront effectués par une fonction lambda qui est invoquée par notre équilibreur de charge d'application (ALB).
La première étape consiste à créer votre fonction lambda en accédant au service Lambda dans AWS et en cliquant sur « Create Function ». Vous serez invité à attribuer un nom à votre fonction lambda et à sélectionner le langage de programmation dans lequel écrire votre fonction. Pour cet exemple, nous utilisons Python comme langage d'exécution.
Nous devons maintenant développer notre fonction lambda. Supposons un instant que notre équilibreur de charge d'application a été configuré et transmet la charge utile du webhook à notre fonction lambda - le lambda recevra une charge utile incluant les en-têtes complets et le corps. La charge utile est transmise dans notre fonction lambda en utilisant l'objet « event » sous forme de dictionnaire. Vous pouvez référencer les en-têtes et le corps de la charge utile de manière indépendante en accédant aux objets « headers » et « body » au sein de la charge utile. Dans cet exemple, nous allons simplement lire l'en-tête « x-messagesystems-batch-id », où l'ID de lot est une valeur unique créée par Bird pour le lot de webhooks, et l'utiliser comme nom de fichier lors du stockage du corps comme fichier plat dans S3 ; cependant, vous pouvez vouloir ajouter des fonctionnalités supplémentaires telles que des vérifications d'authentification ou gestion des erreurs, si nécessaire.
Lors du stockage de la charge utile dans un fichier plat sur S3, nous devrons définir le nom du bucket S3, l'emplacement et le nom du fichier où les données de la charge utile seront stockées. Dans notre exemple de fonction lambda, nous faisons cela dans la fonction « store_batch ». Dans cet exemple, nous allons stocker l'ensemble du lot en un seul fichier, ce qui aide à garantir que les données sont collectées et stockées avant que la connexion HTTP entre Bird et votre point de terminaison ne s'interrompe. Bien que vous puissiez ajuster les paramètres de délai de connexion sur votre équilibreur de charge, il n'y a aucune garantie que la connexion ne sera pas interrompue du côté de la transmission (dans ce cas Bird) ou que la connexion ne sera pas terminée avant que votre fonction lambda ne termine son exécution. Il est préférable de garder votre fonction consommatrice aussi efficace que possible et de réserver les activités de traitement des données pour les processus en aval dans la mesure du possible - comme convertir la charge utile concaténée au format JSON en CSV, ou charger les données d'événement dans une base de données.
Il est important de noter que vous pourriez avoir besoin de mettre à jour les permissions pour votre fonction lambda. Votre rôle d'exécution devra avoir les permissions PutObject et GetObject pour S3. Il est préférable d'appliquer le principe du moindre privilège, donc je recommande d'attribuer ces permissions uniquement au bucket S3 où les charges utiles des webhooks seront stockées.
Un échantillon de notre fonction lambda consommatrice peut être trouvé ici.
Une note rapide sur l'ID de lot : Bird va regrouper les événements en une seule charge utile, où chaque lot peut contenir de 1 à 350 enregistrements d'événements ou plus. Le lot recevra un ID de lot unique, qui peut être utilisé pour visualiser le statut du lot en utilisant l'API Event Webhooks ou dans votre compte Bird en cliquant sur un flux de webhooks et en sélectionnant « Statut des lots ». Dans le cas où une charge utile de webhook ne pourrait pas être livrée, telle qu'une interruption de connexion, Bird va automatiquement réessayer le lot en utilisant le même ID de lot. Cela peut arriver lorsque votre fonction lambda fonctionne près du temps d'aller-retour maximum de 10 secondes et est une raison d'optimiser la fonction consommatrice pour réduire le temps d'exécution.
Pour gérer toutes les activités de traitement des données, je recommande de créer une fonction lambda séparée qui s'exécute chaque fois qu'un nouveau fichier est créé sur le bucket S3 – de cette façon, le traitement des données est effectué de manière asynchrone à la transmission des données, et il n'y a aucun risque de perte de données en raison d'une connexion terminée. Je discute de la fonction lambda de traitement dans une section ultérieure.
Créer un Application Load Balancer
Pour recevoir une charge utile de webhook, nous devons fournir un point de terminaison pour envoyer les charges utiles. Nous faisons cela en créant un équilibreur de charge d'application dans AWS en accédant à EC2 > Load Balancers et en cliquant sur « Create Load Balancer ». Vous serez invité à choisir le type d'équilibreur de charge que vous souhaitez créer - pour cela, nous voulons créer un équilibreur de charge d'application. Nous devons utiliser un équilibreur de charge d'application (ALB) pour construire notre consommateur car les webhooks d'événements seront envoyés sous forme de requête HTTP, et les ALB sont utilisés pour acheminer les requêtes HTTP au sein d'AWS. Nous pourrions implémenter une passerelle HTTP comme alternative ; cependant, nous utilisons un ALB pour ce projet car il est plus léger et plus rentable qu'une passerelle HTTP. Il est important de noter que si vous choisissez d'utiliser une passerelle HTTP, le format des événements peut être différent de celui d'un ALB, et par conséquent, votre fonction lambda devra gérer l'objet de requête en conséquence.
Une fois que votre ALB est créé, vous serez invité à lui attribuer un nom et à configurer le schéma et les paramètres de sécurité/acces - puisque nous prévoyons de recevoir des données d'événement d'une source externe (Bird), nous voudrons que notre ALB soit face à Internet. Sous « Auditeurs et routage », l'ALB devrait écouter HTTPS sur le port 443, et nous voulons créer un groupe cible qui pointe vers notre fonction lambda afin que notre ALB transfère les demandes entrantes à la fonction consommatrice lambda que nous avons créée ci-dessus. Vous devez également vous assurer que le groupe de sécurité a la permission d'accepter le trafic via le port 443.
Créer un enregistrement DNS pour l'équilibreur de charge
Pour nous faciliter l'utilisation de notre ALB en tant que point de terminaison, nous allons créer un enregistrement A dans DNS qui pointe vers notre ALB. Pour cela, nous pouvons utiliser le service AWS Route 53 (ou votre fournisseur DNS actuel) et créer un enregistrement A pour le nom d'hôte que vous souhaitez utiliser pour votre point de terminaison (par exemple, spevents.<your_domain>). L'enregistrement A doit être configuré pour pointer vers l'ALB que nous avons créé. Si vous utilisez Route 53 pour gérer les enregistrements DNS, vous pouvez référencer l'instance ALB directement en activant « Alias » et en sélectionnant l'ALB; autrement, si vous utilisez un fournisseur DNS externe, vous devez pointer l'enregistrement A vers l'adresse IP publique de l'instance ALB.
Je recommande d'utiliser un outils tel que Postman pour tester que tout a été configuré correctement avant d'activer votre webhook Bird. Vous pouvez faire une requête POST à votre point de terminaison et confirmer que vous recevez une réponse. Si votre requête POST ne renvoie pas de réponse, vous devrez peut-être vérifier que votre ALB écoute sur le bon port.
Créer un Webhook Bird
Nous sommes maintenant prêts à créer le webhook dans Bird et à utiliser le nom d'hôte défini par l'enregistrement A ci-dessus en tant que point de terminaison cible. Pour créer le webhook, accédez à la section Webhooks de votre compte Bird et cliquez sur « Create Webhook ». Vous serez invité à attribuer un nom à votre webhook et à fournir une URL cible – la cible doit être le nom d'hôte de l'enregistrement A que vous avez créé précédemment. Notez que l'URL de cible peut nécessiter « HTTPS:// » soit inclus dans l'URL.
Une fois terminé, vérifiez que le bon sous-compte et les événements sont sélectionnés, et appuyez sur « Create Webhook » pour enregistrer votre configuration. Les données d'événement pour tous les types d'événements sélectionnés seront désormais diffusées vers notre URL cible et consommées par notre ALB pour un traitement en aval.
