Comment envoyer des notifications Datama par webhook via un orchestrateur (exemple GA4 BQ GCP) ?

Datama permet d'envoyer des messages contenant des analyses ou des alertes, mais il arrive que les données ne soient pas disponibles à une heure fixe. C'est le cas, par exemple, des données interday de GA4 pour les acteurs du web.

Dans ces cas-là, Datama permet de déclencher l'envoi de notifications depuis un outil externe, via un système de webhook. Cet outil externe, généralement un orchestrateur (sur Google Cloud Platform, il s'agit de Workflows, mais ces opérations peuvent également être réalisées avec des outils comme Apache Airflow, AWS Step Functions ou Azure Logic Apps), appelle le webhook, qui déclenche alors l'analyse et l'envoi du message au bon moment, précisément lorsque les données sont prêtes.

Dans cet exemple, nous allons suivre la procédure de configuration des exports dans Datama selon cette méthode, le « webhook » (une alternative à l'option « scheduled »). L'objectif est de déclencher l'export après un événement survenu dans le datawarehouse (par exemple, la mise à jour ou la création d'une table). Ceci est particulièrement utile lorsqu'on attend des mises à jour de données GA4 qui n'arrivent pas à heure fixe. Si vous n'êtes pas familier avec ce sujet, je vous invite à lire cet article à ce propos.

Dans notre exemple, nous allons suivre la procédure permettant de déclencher la requête une fois que les données GA4 ont été mises à jour, en passant de la table event_intraday à la table event.

A. Créez votre workbook dans Datama

Un prérequis pour ce que nous cherchons à obtenir est de disposer d'un workbook précis dans Datama, que vous souhaitez déclencher via un webhook. Dans notre cas, il s'agira typiquement d'un cas d'usage Datama sourcé sur des tables GA4 dans BigQuery, dont nous voulons nous assurer qu'elles sont à jour.

Une fois celui-ci créé, vous pouvez alors créer un export, puis récupérer un webhook.

B. Définissez le workflow

Avant de pouvoir automatiser l'envoi des exports Datama au bon moment, il est essentiel de mettre en place un workflow. Celui-ci sera activé par un déclencheur (trigger) : dès qu'un événement spécifique se produit dans votre datawarehouse, il appellera automatiquement l'API Datama pour exécuter l'export. Dans notre cas, nous allons configurer un webhook basé sur la suppression de la table event_intraday, garantissant que les données ne sont envoyées qu'une fois entièrement mises à jour. Suivez ces étapes pour configurer efficacement votre webhook dans BigQuery. La première étape consiste à créer un workflow dans votre datawarehouse, dont le but est de déclencher l'appel à l'API d'export Datama via le webhook après une certaine action — dans notre cas, l'insertion des données d'event_intraday dans la table event_. Pour cela, rendez-vous dans BigQuery.

Étape 1 : ouvrez le menu Workflows

• Dans le menu de navigation (en haut à gauche), allez dans Workflows > Workflows, ou recherchez « Workflows » dans la barre de recherche.

Étape 2 : créez un nouveau workflow

• Cliquez sur le bouton « CREATE » pour créer un nouveau workflow.
• Définissez sa région, qui doit correspondre à la région du projet BigQuery sur lequel vous travaillez.
• Dans « Call Log Level », sélectionnez « All calls » ; les appels seront filtrés plus tard dans la section « Trigger ».
• Vous pouvez ajouter des labels à votre webhook, par exemple un label Type=« webhook-job » et un label App=« datama ».

Étape 3 : définissez le déclencheur du workflow

• Dans la section Triggers en bas de page, sélectionnez « Add New Trigger » > « Eventarc ».
• Donnez-lui un nom et sélectionnez « BigQuery » comme Event Provider.
• Pour le type d'événement, nous nous basons sur la suppression de la table event_intraday. Dans la séquence, BigQuery crée une nouvelle table partitionnée pour la nouvelle date, y charge les données, puis supprime la table event_intraday une fois toutes les données chargées. La suppression de cette table garantit donc que toutes les données ont été chargées, c'est pourquoi nous nous appuyons sur cet événement. Nous choisirons donc google.cloud.bigquery.v2.TableService.DeleteTable comme type d'événement.
• Ensuite, pour la partie ressource, deux options sont possibles : soit sélectionner « Any resource » pour voir toutes les suppressions de table et retrouver la bonne dans l'historique des déclenchements, puis sélectionner l'option « Path Pattern » et choisir le bon pattern.
• Soit sélectionner directement « Path Pattern » et retrouver le bon événement dans les logs (voir l'étape 4, optionnelle, pour accéder aux logs). Dans notre cas, le Path Pattern ressemblera à ceci : projects/NAME_OF_PROJECT/datasets/analytics_XXXXXXXXX/tables/*
• Enfin, sélectionnez la région correspondant à la région du projet. Si aucun webhook ne se déclenche dans l'historique alors que des suppressions de table ont bien eu lieu dans le dataset, je vous suggère de sélectionner l'option 1 dans la section « Resource » pour vérifier que le path pattern est correct. Sinon, il peut s'agir d'un problème de région.

Étape 4 (optionnelle) : récupérez les logs

Pour accéder aux logs, vous devrez ouvrir un second onglet de la Google Cloud Console.

• Dans le menu de navigation (en haut à gauche), allez dans Logging > Logs Explorer.
• Dans Logs Explorer, définissez un filtre pour cibler l'activité BigQuery.
• Vous pouvez utiliser la requête avancée suivante pour filtrer les logs de modification d'une table spécifique, par exemple : resource.type=« bigquery_resource » (limite les résultats aux ressources BigQuery)
• resource.labels.dataset_id=« NOM_DU_DATASET » (filtre sur le nom du dataset contenant la table)
• resource.labels.table_id=« NOM_DE_LA_TABLE » (filtre sur le nom de la table)

Étape 5 : définissez le webhook à appeler

• Une fois le déclencheur défini, passez à l'étape suivante. Pour celles et ceux qui ne sont pas familiers avec le code, ne vous inquiétez pas, nous vous donnons les quelques lignes à ajouter :

main: params: [event] steps:

• callDatama: call: http.get args: url: 'https://api.prep.datama.io/v1.0/webhook/XXXXXXXXXXXXXXXXXXXXXXX' result: response

• returnCallOutput: return: '${response}'

• Le seul champ à modifier est « url », que vous pouvez copier depuis le bloc export de Datama : cliquez sur le champ webhook url pour le copier dans votre presse-papiers.

• Cliquez sur Deploy, et votre webhook est prêt à être testé.

Étape 6 : finalisez le workflow

• La finalisation consiste à s'assurer que le webhook fonctionne correctement.
• Commençons par vérifier que le script fonctionne. Allez sur votre webhook et sélectionnez « Execute » dans le menu du haut pour exécuter votre script manuellement :

• Exécutez le programme pour vérifier que tout fonctionne correctement, vous obtiendrez :

Si cela fonctionne et que vous recevez votre export Datama, le script est opérationnel.

• Pour tester le déclencheur, rendez-vous dans le dataset défini dans votre path pattern, créez une table vide puis supprimez-la. Pour simuler la suppression d'une table, vous devriez voir apparaître un appel au webhook sur la page de détails du workflow, et recevoir un export. Si ces deux tests sont concluants, votre webhook est fonctionnel.

C. (optionnel) Mettez à jour le workbook Datama

Notez que l'URL du webhook contient des informations spécifiques à l'export que vous avez défini dans Datama Prep. Cela implique que chaque fois que vous modifiez le moindre paramètre dans Datama, l'adresse du webhook change.

Il est donc nécessaire de copier le nouveau lien dans Datama Prep et de le remplacer dans le code défini à l'étape 5. Le nouveau lien à coller doit remplacer celui présent à l'endroit suivant : « url: 'nouvelle URL de webhook à coller' ».

Conclusion

En intégrant un webhook à votre workflow BigQuery, vous optimisez l'envoi des exports Datama en les déclenchant précisément au bon moment, sans dépendre d'un planning fixe. Cette approche garantit que vos analyses s'appuient sur des données fraîches et complètes, en particulier pour GA4. Grâce à une configuration rigoureuse — de la définition du trigger à la validation du workflow — vous sécurisez un processus automatisé, fiable et réactif.

En résumé, cette méthode vous permet de tirer un usage plus efficace et plus pertinent de vos données.