Aller au contenu
Cercle IA Tech · Intégration Un site du réseau Cercle IA Tech

Guide

API Google Agenda : être prévenu des changements

Notifications push de l'API Google Calendar pour un assistant IA : canal watch, HTTPS, expiration sans renouvellement automatique, pas de contenu.

Mis à jour le

Un assistant IA qui prépare vos rendez-vous, propose des créneaux ou résume votre journée doit savoir quand l'agenda change. Interroger l'API toutes les minutes gaspille des appels. Google Agenda propose des notifications push : il appelle une adresse de votre serveur quand une ressource change. Ce qui suit vient de la documentation de l'API Calendar, lue le 16/11/2026.

Si une notification doit déclencher une demande à un assistant, examinez les opérations prévues par l’API d’ALMA. Conservez dans votre intégration la lecture de l’événement concerné et le contrôle des doublons avant le traitement.

Ce qu'on peut surveiller

La méthode watch existe pour quatre ressources : les règles d'accès (Acl), la liste des agendas (CalendarList), les événements (Events) et les réglages (Settings). Pour un assistant, ce sont presque toujours les événements.

Créer un canal de notification

On envoie une requête POST à la méthode watch de la ressource, sous la forme https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch, avec un jeton d'accès. La demande échoue si l'utilisateur concerné n'est ni propriétaire de la ressource ni autorisé à y accéder. Les champs sont :

Champ Statut Contenu
id obligatoire Chaîne unique dans votre projet, 64 caractères au plus ; un UUID est recommandé
type obligatoire La valeur web_hook
address obligatoire L'adresse de rappel, qui « doit utiliser HTTPS »
token facultatif Chaîne libre de 256 caractères au plus, renvoyée dans l'en-tête X-Goog-Channel-Token ; à ne pas utiliser pour une donnée sensible
expiration facultatif Horodatage Unix en millisecondes de l'arrêt des notifications

La réponse 200 OK contient resourceId et resourceUri. Gardez-les : ils servent à arrêter le canal. Le serveur doit présenter un certificat SSL valide ; un certificat auto-signé, non fiable, révoqué ou dont le nom ne correspond pas à l'hôte est refusé.

Ce que votre serveur reçoit

La notification n'a pas de corps. Elle arrive avec des en-têtes : X-Goog-Channel-ID, X-Goog-Message-Number, X-Goog-Resource-ID, X-Goog-Resource-State (valeurs sync, exists ou not_exists) et X-Goog-Resource-URI. Selon les cas s'ajoutent X-Goog-Channel-Expiration et X-Goog-Channel-Token. Le premier message est un message sync, de numéro 1 ; les suivants croissent sans être consécutifs.

Votre serveur répond 200, 201, 202, 204 ou 102 pour confirmer. Si vous utilisez la bibliothèque cliente de Google, les réponses 500, 502, 503 et 504 déclenchent des nouvelles tentatives avec attente croissante ; tout autre code compte comme un échec.

Comme la notification ne dit pas ce qui a changé, le schéma habituel est : recevoir, répondre vite, mettre dans une file, puis lire l'agenda. C'est le montage de la page webhook et IA.

Expiration et renouvellement

L'expiration retenue est la plus stricte entre votre demande et les limites internes de Google Agenda ; la documentation ne donne pas de durée par défaut. Il n'y a pas de renouvellement automatique : avant l'échéance, on rappelle watch avec un nouvel id. Les deux canaux peuvent coexister un temps. Un canal qu'on oublie de renouveler s'éteint sans bruit, et l'assistant cesse de voir l'agenda. Inscrivez l'échéance dans votre suivi, comme le propose la page mise en production.

Arrêter un canal

Un POST sur https://www.googleapis.com/calendar/v3/channels/stop avec l'id du canal et le resourceId. Seul l'utilisateur qui a créé le canal depuis le même client peut l'arrêter, sauf si un compte de service l'a créé.

Ne pas s'y fier seul

Google écrit que les notifications ne sont pas fiables à 100 % et que certains messages peuvent être perdus. Votre application doit donc se resynchroniser correctement même quand rien n'arrive, par exemple par une relecture périodique. Cette combinaison de l'événement et de la relecture est discutée dans Alaisia · Intégrateurs, synchronisation ou temps réel.

Si votre accès à l'agenda passe par un compte de service au nom des utilisateurs, voir aussi la délégation au niveau du domaine Google Workspace.

Questions fréquentes

Que contient une notification push de Google Agenda ?

Aucun corps de message. Elle signale qu'une ressource a changé, pas ce qui a changé : il faut ensuite interroger l'API pour obtenir le détail.

Le canal de notification se renouvelle-t-il tout seul ?

Non. Il n'y a pas de renouvellement automatique : avant l'expiration, on rappelle watch avec un nouvel identifiant de canal.

Peut-on compter sur les notifications pour ne rien rater ?

Non. La documentation indique qu'elles ne sont pas fiables à 100 % et que l'application doit se resynchroniser correctement même sans notification.

Sources

Pages consultées pour écrire cet article :

  1. https://alma.iarche.fr/fr/api-docs
  2. https://developers.google.com/workspace/calendar/api/guides/push

À lire aussi