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 que les expéditeurs puissent envoyer automatiquement des données à leurs systèmes. Cela peut alimenter l'automatisation en aval, telle que la mise à jour des listes de diffusion, le déclenchement de parcours d'email automatisés ou la population 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 Event Search, ou programmatiquement en utilisant le Events API de Bird, des limites sur le nombre d'enregistrements renvoyés dans une seule requête ou des limitations de taux sur le point de terminaison API peuvent rendre ces deux méthodes restrictives pour les expéditeurs de grande envergure.
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 celles-ci peuvent être consommées sans avoir à planifier des tâches cron qui récupèrent les données. Il y a aussi des compromis logistiques lorsque vous récupérez les données par rapport à le fait de les recevoir, 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 poussées vers votre point de terminaison dès qu'elles sont disponibles dans Bird.
Bien que les avantages de recevoir des données d'événements en temps réel pour alimenter des processus d'automatisation en aval puissent être compris immédiatement par de nombreux expéditeurs, le processus réel pour implémenter et consommer les webhooks peut être intimidant. Cela peut être particulièrement vrai si vous n'êtes pas familier avec les composants techniques de création d'un point de terminaison et de gestion des données de manière programmatique. Il existe des services qui consomment les données de webhook de Bird et les intègrent automatiquement dans votre base de données – un exemple serait StitchData, dont nous avons parlé dans notre blog par le passé. 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 dans AWS.
Configuration de l'Endpoint de Cible Webhook
Lorsqu’un événement Bird est créé, nous souhaitons que les données de l'événement soient diffusées en temps réel vers un point de terminaison dans AWS afin que nous puissions les consommer et les utiliser de manière programmatique. 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 compartiment S3. Un diagramme 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 compartiment S3 où nous stockerons nos données d'événement, puis en travaillant à rebours – en ajoutant chaque composant qui s’intègre dans ce que nous avons construit.
Créer un compartiment S3 pour stocker les données de Webhook
Avant de créer notre équilibrage de charge pour accepter les données, ou notre fonction lambda pour stocker les données, nous devons d'abord créer notre compartiment S3 où les données seront stockées. Pour ce faire, accédez au service S3 dans AWS et appuyez sur “Créer un compartiment.” Vous serez invité à attribuer un nom à votre compartiment et à définir la région – assurez-vous d'utiliser la même région que votre ALB et fonction lambda. Lorsque votre compartiment S3 est créé, il sera vide – si vous souhaitez organiser les données dans un dossier, vous pouvez soit créer le répertoire prévu maintenant, soit le répertoire sera créé lorsque votre fonction lambda stockera le fichier. Dans cet exemple, nous avons nommé notre compartiment 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 des données seront effectués par une fonction lambda qui est invoquée par notre application d'équilibrage de charge (ALB).
La première étape consiste à créer votre fonction lambda en accédant au service Lambda dans AWS et en cliquant sur “Créer une fonction.” Vous serez invité à attribuer un nom à votre fonction lambda et à choisir dans quel langage de programmation é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 équilibrage 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 et le corps complets. La charge utile est transmise à notre fonction lambda en utilisant l'objet “event” en tant que dictionnaire. Vous pouvez référencer les en-têtes et le corps de la charge utile indépendamment en accédant aux objets “headers” et “body” dans 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 webhook, et l'utiliser comme nom de fichier lorsqu'on enregistre le corps en tant que fichier plat dans S3; cependant, vous pouvez vouloir ajouter des fonctionnalités supplémentaires telles que des vérifications d'authentification ou la gestion des erreurs, si nécessaire.
Lorsque nous stockons la charge utile dans un fichier plat sur S3, nous devons définir le nom du compartiment S3, l'emplacement et le nom de fichier du fichier où les données de la charge utile seront stockées. Dans notre fonction lambda d'exemple, 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 n'expire. Bien que vous puissiez ajuster les paramètres d'expiration de connexion sur votre équilibrage de charge, il n'y a aucune garantie que la connexion n'expirera pas du côté de la transmission (dans ce cas Bird) ou que la connexion ne sera pas terminée avant que votre fonction lambda n'ait fini de s'exécuter. Il est conseillé de rendre votre fonction de consommateur aussi efficace que possible et de réserver les activités de traitement des données pour les processus en aval lorsque cela est possible – comme convertir la charge utile au format JSON en fichier CSV, ou charger les données d'événement dans une base de données.
Il est important de noter que vous devrez peut-être mettre à jour les autorisations pour votre fonction lambda. Votre rôle d'exécution aura besoin des autorisations PutObject et GetObject pour S3. Il est conseillé d'appliquer le principe de moindre privilège, donc je recommande de définir ces autorisations uniquement pour le compartiment S3 où les charges utiles du webhook seront stockées.
Un exemple de notre fonction lambda de consommateur peut être trouvé ici.
En guise de note rapide sur l’ID de lot: Bird va mettre en lot 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 l'état du lot en utilisant le Event Webhooks API ou dans votre compte Bird en cliquant sur un flux de webhook et en sélectionnant “Batch Status.” Dans le cas où une charge utile de webhook ne pourrait pas être livrée, comme lors d'un dépassement de délai de connexion, Bird réessaiera automatiquement le lot en utilisant le même ID de lot. Cela peut se produire lorsque votre fonction lambda tourne proche du temps maximum aller-retour de 10 secondes et c'est une raison pour optimiser la fonction de consommateur 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 compartiment S3 – de cette manière, le traitement des données est effectué de manière asynchrone par rapport à 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 la fonction lambda de traitement dans une section ultérieure.
Créer un équilibrage de charge d'application
Pour recevoir une charge utile de webhook, nous devons fournir un point de terminaison vers lequel envoyer les charges utiles. Nous faisons cela en créant un équilibrage de charge d'application dans AWS en accédant à EC2 > Load Balancers et en cliquant sur “Créer un Load Balancer.” Vous serez invité à choisir quel type de load balancer vous voulez créer – pour ceci, nous voulons créer un équilibrage de charge d'application. Nous devons utiliser un équilibrage de charge d'application (ALB) pour construire notre consommateur parce que les webhooks d'événement seront envoyés en tant que requête HTTP, et les ALBs sont utilisés pour router les requêtes HTTP au sein d'AWS. Nous pourrions implémenter une Passerelle HTTP en guise d’alternative; cependant, nous utilisons un ALB pour ce projet car c’est plus léger et plus économique qu’une Passerelle HTTP. Il est important de noter que si vous choisissez d'utiliser une Passerelle HTTP, le format d'événement 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 votre ALB créé, vous serez invité à attribuer un nom à votre ALB et à configurer le schéma et les paramètres d'accès/sécurité – puisque nous prévoyons de recevoir des données d'événement d'une source externe (Bird), nous voudrons que notre ALB soit orienté vers Internet. Sous “Écouteurs et routage,” l'ALB doit écouter HTTPS sur le port 443, et nous voulons créer un groupe de cibles qui pointe vers notre fonction lambda afin que notre ALB transfère les requêtes entrantes à la fonction lambda de consommation 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'équilibrage de charge
Pour nous faciliter l'utilisation de notre ALB en tant que point de terminaison, nous allons créer un enregistrement A dans le 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; sinon, 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 outil 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 qu'une réponse est reçue. Si votre requête POST ne renvoie pas de réponse, vous devrez peut-être vérifier que votre ALB écoute 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 comme point de terminaison cible. Pour créer le webhook, accédez à la section Webhooks dans votre compte Bird et cliquez sur “Créer un 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 cible peut nécessiter que “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 “Créer un 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.
