Vue d’ensemble des webhooks

Comment la Listings API envoie les événements du compte à votre serveur, les événements disponibles et les cinq contrôles requis pour chaque livraison.

Interroger régulièrement une API pour savoir si quelque chose a changé est coûteux et entraîne toujours un léger retard. Les webhooks inversent ce fonctionnement : lorsqu’un événement se produit sur votre compte (un avis arrive, un établissement est modifié, une publication Google Business est mise en ligne), la Listings API envoie en quelques secondes une requête HTTP POST avec un corps JSON à une URL que vous contrôlez.

Il existe une seule URL de webhooks par compte et aucun abonnement par événement. Si les webhooks sont activés pour votre compte et que votre point de terminaison est vérifié, chaque événement répertorié sur cette page est envoyé à cette URL unique. Adaptez le traitement selon le champ event et ignorez ce dont vous n’avez pas besoin.

Le processus de livraison

Chaque événement suit le même parcours. Les 5 conditions sont vérifiées dans l’ordre ; si l’une d’elles n’est pas remplie, aucune requête HTTP n’est effectuée, mais la tentative reste enregistrée.

Ce que vous pouvez recevoir

18 événements répartis en 6 familles. Chacun correspond à une ressource que vous gérez déjà via l’API REST : le webhook vous indique donc quand un changement se produit, et le point de terminaison vous indique ce qui a changé.

Famille	Événements	Ressource REST associée
`listing.submission`	1	Fiches
`profile.*`	3 : création, modification, suppression	Établissements
`connection.*`	6 : connexion, déconnexion, réauthentification, accès impossible, 2 × vérification Google	Comptes connectés
`interaction.*`	2 : avis, réponse	Avis
`local_post.*`	4 : création, mise en ligne, rejet, suppression	Publications
`review_analytics.*`	2 : instantanés quotidien et hebdomadaire	Statistiques

Les tableaux complets des champs et des exemples de charges utiles figurent dans la référence des événements.

Hors périmètre

La plateforme émet d’autres familles d’événements que la Listings API ne documente pas et ne prend pas en charge, car aucun point de terminaison REST n’est publié ici pour ces familles. Elles sont répertoriées pour éviter qu’une omission ne paraisse accidentelle :

Campagnes d’avis : campaign.*
Classements : rankings.*
Publications et promotions Social : social_post.*
Connexions Social : social_connection.*
Idées de publications générées par IA : idea.*, idea_series.*, idea_pipeline.*, idea_image.*
Propriété Google Business Profile : gbp_ownership.*

2 points à connaître avant de commencer le développement

Les événements de vérification Google indiquent uniquement le résultat, mais le statut peut être consulté

connection.google_verification_verified et connection.google_verification_failed vous indiquent le résultat d’une vérification Google Business Profile. Aucun point de terminaison REST ne lance de vérification : seul le webhook vous indique qu’une tentative est terminée. Le statut lui-même n’est pas accessible uniquement par webhook : chaque lecture d’établissements (liste, recherche, par identifiants) renvoie googleVerificationStatus: { status, message }. Consultez-le si vous manquez un événement et interrogez-le régulièrement pendant une vérification, car les états intermédiaires n’émettent aucun événement. Consultez la référence des événements pour connaître les valeurs du statut.

Conditions d’envoi

L’envoi dépend de cinq conditions, vérifiées dans cet ordre. La première condition non remplie bloque l’envoi ; les conditions suivantes ne sont jamais vérifiées.

#	Condition	Si elle n’est pas remplie
1	Votre forfait inclut les webhooks. Un droit d’accès associé au compte.	Rien n’est enregistré. L’événement ne vous est tout simplement pas acheminé.
2	Une URL de webhooks est configurée sur le compte.	Rien n’est enregistré.
3	La vérification du point de terminaison a réussi : cette condition n’est imposée qu’une fois qu’un secret de signature existe.	Enregistré avec le statut `endpoint_unverified`.
4	L’URL se résout en une adresse publique (HTTPS, nom d’hôte résolvable publiquement).	Enregistré avec le statut `blocked_url`.
5	Vous respectez la limite de webhooks de votre forfait.	Enregistré avec le statut `rate_limited`. L’événement est abandonné, sans être mis en file d’attente.

Les comptes sans secret de signature conservent le fonctionnement antérieur (sans signature)

Si votre compte possède une URL de webhooks, mais n’a jamais généré de secret de signature, les événements sont envoyés sans signature, et la condition 3 est entièrement ignorée. Ce fonctionnement permet de maintenir les intégrations antérieures à l’introduction de la signature ; vous ne devez pas vous appuyer dessus pour créer une intégration. Dès que vous générez un secret, la signature devient obligatoire et la vérification devient une condition bloquante : la génération d’un secret suspend donc les envois jusqu’à ce que vous vérifiiez le point de terminaison. Planifiez soigneusement cette transition : implémentez le contrôle des signatures et l’échange de vérification avant de cliquer sur Generate.

Forfaits et limites

Les webhooks sont inclus dans tous les forfaits : Launch, Growth et Enterprise. La période d’essai utilise le forfait que vous avez choisi ; les comptes d’essai disposent donc des webhooks dès le premier jour, dans les limites de ce forfait. Le droit d’accès est lié à votre forfait : il est donc accordé ou retiré lors d’un changement de forfait, sans effet immédiat ; attendez-vous à ce qu’il prenne effet lors de votre prochain changement de forfait ou de la synchronisation liée à l’inscription, et non au moment où vous cliquez pour passer au forfait supérieur. La page Webhooks du tableau de bord affiche votre droit d’accès et vos plafonds en vigueur.

Les envois sont également comptabilisés par rapport à un plafond par minute et à un plafond par jour, tous deux définis par votre forfait.

Forfait	Par minute	Par jour
Launch	10	7,200
Growth	50	36,000
Enterprise	Illimité	Illimité

Les plafonds de webhooks correspondent aux limites de requêtes API de votre forfait : le quota d’événements que nous vous envoyons est égal au quota de requêtes que vous nous envoyez.

Un plafond ne commence à s’appliquer à votre compte qu’une fois les limites de votre forfait synchronisées avec le système d’envoi. Tant que cette synchronisation n’a pas eu lieu, aucun plafond n’est à vérifier : aucun envoi n’est donc comptabilisé ni abandonné. Un compte nouvellement créé peut ainsi bénéficier d’envois non comptabilisés avant que le plafond de son forfait ne s’applique. N’interprétez pas l’absence de rate_limited comme la preuve que vous êtes en dessous de la limite.

Fonctionnement du comptage :

Deux fenêtres fixes indépendantes : une par minute, une par jour. Il n’existe pas de fenêtre par heure pour les webhooks. (Le limiteur de débit des requêtes est un système distinct, avec des fenêtres différentes ; les deux ne partagent pas de quota.)
Les fenêtres sont alignées sur le calendrier, et ne sont pas glissantes : le compteur par minute est remis à zéro au début de chaque minute, et le compteur journalier au début de chaque journée UTC.
En cas de dépassement, l’événement est abandonné. Il n’est ni mis en file d’attente, ni retardé, ni réessayé : aucune file de nouvelles tentatives n’existe dans le circuit d’envoi, et aucun appelant n’est présent pour recevoir un 429 en retour. La tentative est enregistrée avec le statut d’envoi rate_limited afin que la perte soit visible et ne passe pas inaperçue.
En cas de défaillance, le limiteur laisse passer les envois. Si le limiteur lui-même ne peut pas répondre, l’envoi est effectué au lieu d’être abandonné. Vous ne perdrez jamais d’événement à cause d’un compteur défaillant.

Le seul contrôle de volume intégré du côté de la production des événements est un mécanisme anti-rebond sur profile.updated : au maximum un envoi par établissement par période de 60 secondes, effectué au début de la fenêtre. Les modifications rapprochées d’un même établissement sont regroupées en un seul événement, et les changed_fields que vous recevez décrivent uniquement la modification qui a ouvert la fenêtre. Aucun autre événement n’est soumis à ce mécanisme.

Comme l’envoi est effectué au début de la fenêtre, vous le recevez au début de la période de 60 secondes : une relecture des données déclenchée à sa réception ne voit que la première modification. Planifiez une seconde relecture une fois la fenêtre fermée, au moins 60 secondes après l’événement, et effectuez également une réconciliation périodique des établissements, puisque l’événement lui-même ne fait l’objet que d’une tentative d’envoi, sans nouvelle tentative. Consultez la procédure de récupération après un événement manqué.

Configuration

Mettez en place un point de terminaison HTTPS. Son adresse doit pouvoir être résolue publiquement, son certificat doit être valide, et il doit accepter POST et renvoyer 2xx en moins de 5 secondes. Les adresses privées et internes (bouclage, RFC-1918, adresses locales au lien, adresses IP des services de métadonnées cloud) sont refusées.
Enregistrez l’URL de vos webhooks sur la page Webhooks du tableau de bord. Une seule URL par compte, pour tous les événements.
Générez un secret de signature et stockez-le sur votre serveur. Il n’est affiché qu’une seule fois. À partir de ce moment, les envois sont signés et la vérification est obligatoire.
Vérifiez le point de terminaison. La plateforme envoie un défi signé ; votre point de terminaison répond avec un HMAC du nonce au format hexadécimal. Si la vérification réussit, le point de terminaison passe à l’état vérifié et les envois commencent. Consultez Signatures et vérification pour connaître les spécifications exactes et obtenir du code fonctionnel.
Traitez les événements. Vérifiez la signature, placez la charge utile dans une file d’attente et renvoyez 200. Effectuez le traitement proprement dit en dehors du traitement de la requête. Consultez Comportement des envois pour connaître le délai d’expiration, la politique de tentative unique et le comportement attendu concernant les doublons et l’ordre des événements.

Pour continuer

Signatures et vérification : l’en-tête X-ListingsAPI-Signature, la règle concernant le corps brut de la requête et l’échange de vérification.
Comportement des envois : la charge utile standard, le délai d’expiration de 5 secondes, les raisons de l’absence de nouvelles tentatives et tous les états d’envoi.
Référence des événements : les 18 événements, champ par champ.