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 les expéditeurs afin de faire pousser automatiquement les données vers leurs systèmes. Cela peut entraîner des automatisations en aval telles que la mise à jour des listes de diffusion, le déclenchement de parcours de courrier électronique automatisés ou la population de tableaux de bord internes. Bien que les mêmes données d'événement puissent être consultées via l'interface utilisateur de Bird en utilisant Event Search, ou programmatiquement en utilisant l'API Events API de Bird, les limites placées sur le nombre de dossiers renvoyés dans une seule requête ou les limites de débit placées sur le point d'accès 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 d'accès où Bird transmet les données, et les données peuvent être consommées sans avoir à programmer 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 au lieu de les faire pousser vers vous, comme l'identification de la période de temps et des paramètres à utiliser pour chaque requête API. Si les périodes de temps ne sont pas parfaitement alignées, vous risquez de manquer des données, et si les périodes de temps 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énement sont simplement poussées vers votre point d'accès au fur et à mesure qu'elles deviennent disponibles dans Bird.
Bien que les avantages de recevoir des données d'événement en temps réel pour faciliter les processus d'automatisation en aval puissent être immédiatement compris par de nombreux expéditeurs, le processus réel d'implémentation et de consommation des webhooks peut être intimidant. Cela peut être particulièrement vrai si vous n'êtes pas familiarisé avec les composants techniques de la création d'un point d'accès et de la gestion des données de manière programmatique. Il existe des services disponibles qui consommeront les données du webhook Bird et les intégreront 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 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 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 souhaitons que les données de cet événement soient diffusées en temps réel vers un point de terminaison sur AWS afin de pouvoir 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 transférera 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 flux de travail, construisons-les en fait dans l'ordre inverse en commençant par créer un compartiment S3 où nous stockerons nos données d'événement, puis travaillons à rebours – en ajoutant chaque composant qui alimente ce que nous avons construit.
Créer un compartiment S3 pour stocker les données de 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 compartiment S3 où les données seront stockées. Bien que S3 offre un excellent stockage pour les données de webhook, les organisations utilisant également des bases de données PostgreSQL pour le traitement des événements devraient mettre en œuvre des procédures de sauvegarde et de restauration appropriées pour protéger leurs données structurées parallèlement à leur stratégie de stockage S3. 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 la fonction lambda. Lorsque votre compartiment S3 est créé, il sera vide – si vous souhaitez organiser les données à l'intérieur d'un dossier, vous pouvez créer le répertoire prévu maintenant, ou 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 réels des données seront effectués par une fonction lambda 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 « Créer une fonction ». Vous serez invité à attribuer un nom à votre fonction lambda et à choisir 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. Pendant un instant, supposons 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 et le corps complet. La charge utile est transmise à notre fonction lambda en utilisant l'objet "event" comme un 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" 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 lors de la sauvegarde du corps sous forme de fichier plat dans S3 ; cependant, vous pourriez vouloir ajouter des fonctionnalités supplémentaires comme des vérifications d'authentification ou la gestion des erreurs, selon vos besoins.
Lors de la sauvegarde de la charge utile sous forme de fichier plat sur S3, nous devrons 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 le faisons dans la fonction "store_batch". Dans cet exemple, nous allons stocker l'ensemble du lot comme un seul fichier, ce qui permet de s'assurer 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 d'expiration de la connexion sur votre équilibreur de charge, il n'y a aucune garantie que la connexion ne sera pas interrompue côté transmission (dans ce cas Bird) ou que la connexion ne sera pas terminée avant la fin de l'exécution de votre fonction lambda. Il est préférable de conserver votre fonction consommatrice aussi efficace que possible et de réserver les activités de traitement des données pour des processus en aval dans la mesure du possible - comme la conversion de la charge utile au format JSON en fichier CSV, ou le chargement des données d'événement dans une base de données.
Il est important de noter que vous devrez peut-être mettre à jour les permissions de votre fonction lambda. Votre rôle d'exécution devra disposer des permissions PutObject et GetObject pour S3. Il est préférable de faire respecter le principe du moindre privilège, donc je recommande de définir ces permissions uniquement pour le compartiment S3 où les charges utiles des webhooks seront stockées.
Un exemple de notre fonction lambda consommatrice peut être trouvé ici.
Une note rapide sur l'ID de lot : Bird regroupera des événements dans une seule charge utile, où chaque lot peut contenir de 1 à 350 ou plus enregistrements d'événements. Le lot recevra un ID de lot unique, qui peut être utilisé pour voir l'état du lot en utilisant l'API des Webhooks d'événement ou dans votre compte Bird en cliquant sur un flux de webhook et en sélectionnant "État du lot". Dans le cas où une charge utile de webhook ne pourrait pas être livrée, comme lors d'un délai d'expiration de la connexion, Bird va automatiquement réessayer le lot en utilisant le même ID de lot. Cela peut se produire lorsque votre fonction lambda fonctionne près du temps de réponse maximal de 10 secondes, et c'est une raison pour 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 distincte qui s'exécute chaque fois qu'un nouveau fichier est créé dans le compartiment S3 - de cette façon, 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 de la fonction lambda de traitement dans une section ultérieure.
Créer un équilibreur de charge d'application
Pour recevoir une charge utile de webhook, nous devons fournir un point de terminaison pour envoyer les charges utiles. Nous le faisons en créant un équilibreur de charge d'application dans AWS en accédant à EC2 > Load Balancers et en cliquant sur « Créer un équilibreur de charge ». Vous serez invité à choisir quel type d'équilibreur de charge 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 la forme d'une requête HTTP, et les ALB sont utilisés pour acheminer les requêtes HTTP au sein de AWS. Nous pourrions implémenter une passerelle HTTP en alternative ; cependant, nous utilisons un ALB pour ce projet car il est plus léger et moins coûteux qu'une passerelle HTTP. Il est important de noter que si vous choisissez d'utiliser une passerelle HTTP, le format de l'événement peut être différent de celui d'un ALB, et donc votre fonction lambda devra gérer l'objet de la 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 voulons que notre ALB soit accessible par Internet. Sous « Écouteurs 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 redirige les demandes entrantes vers la fonction consommatrice de lambda que nous avons créée ci-dessus. Vous devez également vous assurer que le groupe de sécurité dispose des autorisations pour 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.<votre_domaine>). Lorsque vous travaillez avec DNS à grande échelle sur AWS, soyez conscient qu'il existe des limites DNS non documentées qui peuvent affecter les applications à fort volume, notamment celles gérant de grandes quantités de trafic sortant comme les systèmes de livraison de courrier électronique. 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 directement l'instance ALB 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 outil tel que Postman pour tester que tout a été configuré correctement avant d'activer votre webhook Bird. Vous pouvez effectuer une requête POST vers 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 notre point de terminaison cible. Pour créer le webhook, accédez à la section des Webhooks dans votre compte Bird et cliquez sur « Créer un Webhook ». Vous serez invité à attribuer un nom pour 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 sous-compte et les événements corrects 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 transmises à notre URL cible et consommées par notre ALB pour un traitement en aval.
