Riferimento degli eventi

Tutti i 26 eventi webhook di Listings API, raggruppati per risorsa, con i campi esatti e un payload di esempio per ciascuno.

Ventisei eventi, raggruppati per la risorsa REST a cui si riferiscono. Ogni evento di questa pagina viene inviato al tuo unico URL per i webhook. Non sono previste sottoscrizioni per singolo evento, quindi gestisci gli eventi in base a event e ignora quelli che non ti servono.

Tutti usano il payload standard tranne listing.submission, descritto di seguito. I campi facoltativi all'interno di data vengono omessi quando sono vuoti, anziché essere inviati come null.

Indice

Evento	Risorsa	Si attiva quando
`listing.submission`	Schede	L'invio di una citazione a un sito di directory raggiunge uno stato finale
`profile.created`	Sedi	Viene creata una sede
`profile.updated`	Sedi	Viene modificata una sede
`profile.deleted`	Sedi	Viene archiviata una sede
`connection.location_connected`	Account collegati	Viene collegata una scheda Google o Facebook
`connection.location_disconnected`	Account collegati	Viene scollegata una scheda
`connection.reauth_required`	Account collegati	Le credenziali sono state invalidate
`connection.listing_inaccessible`	Account collegati	È stato perso l'accesso a una scheda
`connection.google_verification_verified`	Account collegati	La verifica di Google è riuscita
`connection.google_verification_failed`	Account collegati	La verifica di Google non è riuscita
`interaction.review`	Recensioni	Arriva o viene modificata una recensione
`interaction.response`	Recensioni	Viene pubblicata o modificata una risposta
`local_post.created`	Post	Viene creato un post
`local_post.published`	Post	Un post viene pubblicato su Google
`local_post.rejected`	Post	Google ha rifiutato un post
`local_post.deleted`	Post	Viene eliminato un post
`social_post.created`	Social	Viene creato un post sui social
`social_post.published`	Social	Un post sui social viene pubblicato su tutti i canali di destinazione
`social_post.failed`	Social	La pubblicazione non è riuscita su almeno un canale
`social_post.rejected`	Social	Un flusso di approvazione ha rifiutato il post
`social_post.deleted`	Social	Viene archiviato un post sui social
`social_connection.connected`	Social	Un canale del brand viene collegato o ricollegato
`social_connection.disconnected`	Social	Un canale del brand viene rimosso intenzionalmente
`social_connection.archived`	Social	Un canale del brand viene perso involontariamente
`review_analytics.daily_snapshot`	Analisi	Viene eseguita l'aggregazione giornaliera delle recensioni
`review_analytics.weekly_snapshot`	Analisi	Viene eseguita l'aggregazione settimanale delle recensioni

Schede

È associato agli endpoint delle schede, in particolare a GET /locations/{locationId}/listings/premium, che restituisce, per ogni citazione, i valori di syncStatus e listingUrl comunicati da questo evento.

listing.submission

Attivazione: l'invio di una citazione per una sede su un sito di directory raggiunge uno stato finale.

Livello principale:

Campo	Tipo	Descrizione
`event`	string	Sempre `listing.submission`.
`data`	object	Vedi di seguito.
`status`	string	`success`, `incomplete` o `canceled`.
`live_link`	string	L'URL della scheda pubblicata. Presente solo con `success` e solo quando è noto.
`error_message`	string	Il motivo per cui non è stato possibile completare l'invio. Presente solo con `incomplete`.

All'interno di data:

Campo	Tipo	Descrizione
`business_id`	integer	L'ID numerico della sede.
`v4_business_id`	string	La codifica base64 di `Location:<id>`, nel formato dell'ID globale.
`location_id`	string	Lo stesso ID globale in base64, non una stringa numerica.
`site.id`	integer	L'ID del sito di directory.
`site.name`	string	Il nome del sito di directory, e.g. `Yelp`.
`site.url`	string	L'URL della pagina iniziale del sito di directory.

JSON

{  "event": "listing.submission",  "data": {    "business_id": 279381,    "v4_business_id": "TG9jYXRpb246Mjc5Mzgx",    "location_id": "TG9jYXRpb246Mjc5Mzgx",    "site": {      "id": 42,      "name": "Yelp",      "url": "https://www.yelp.com"    }  },  "status": "success",  "live_link": "https://www.yelp.com/biz/acme-dental-downtown"}

Sedi

Ciclo di vita della sede, in corrispondenza 1:1 con createLocation, updateLocation e archiveLocations. L'ambito è la singola sede: location_id è sempre una stringa numerica.

profile.created

Attivazione: viene creata una nuova sede.

Campo di `data`	Tipo	Descrizione
`source`	string	Chi l'ha creata: `user`, `api` o `bulk_edit`.

JSON

{  "event": "profile.created",  "timestamp": "2026-08-25T10:04:00Z",  "account_id": 11073,  "location_id": "901234",  "data": { "source": "api" }}

profile.updated

Attivazione: vengono modificati i dettagli di una sede esistente.

Il debounce limita l'invio a una volta per sede ogni 60 secondi, all'inizio dell'intervallo. Le modifiche all'interno dell'intervallo vengono accorpate, non ritardate. Non vengono mai inviate. Considera changed_fields un'indicazione della modifica che ha aperto l'intervallo, non un diff completo.

L'evento arriva all'inizio dell'intervallo, quindi una lettura della sede al suo arrivo mostra solo la prima modifica. Pianifica una seconda lettura dopo la chiusura dell'intervallo, almeno 60 secondi dopo, ed esegui anche una riconciliazione periodica delle sedi, poiché per questo evento viene effettuato un solo tentativo di invio, senza ulteriori tentativi. Vedi come recuperare un evento mancato.

Campo di `data`	Tipo	Descrizione
`source`	string	`user`, `api` o `bulk_edit`.
`changed_fields`	array di string	I nomi dei campi della sede che sono stati modificati, e.g. `name`, `phone`, `address1`. Omesso se vuoto.

JSON

{  "event": "profile.updated",  "timestamp": "2026-08-25T10:06:12Z",  "account_id": 11073,  "location_id": "901234",  "data": {    "source": "user",    "changed_fields": ["name", "phone"]  }}

profile.deleted

Attivazione: viene archiviata una sede. Si tratta di un'eliminazione logica. Non è prevista un'eliminazione definitiva e l'archiviazione può essere annullata con cancelArchiveLocations, che non genera alcun evento.

Campo di `data`	Tipo	Descrizione
`source`	string	`user`, `api` o `bulk_edit`.

JSON

{  "event": "profile.deleted",  "timestamp": "2026-08-25T10:20:44Z",  "account_id": 11073,  "location_id": "901234",  "data": { "source": "user" }}

Account collegati

Ciclo di vita e stato delle connessioni a Google e Facebook, insieme agli endpoint Account collegati. Ambito limitato alla singola sede. platform è sempre google o facebook; gli altri provider non emettono questi eventi.

connected_account_id è sempre presente come chiave, ma ha valore null nei due eventi di verifica di Google.

connection.location_connected

Attivazione: una scheda Google o Facebook viene collegata a una sede.

Campo `data`	Tipo	Descrizione
`platform`	string	`google` o `facebook`.
`connected_account_id`	string	L'account connesso che è stato collegato.

JSON

{  "event": "connection.location_connected",  "timestamp": "2026-08-25T14:32:10Z",  "account_id": 11073,  "location_id": "279381",  "data": {    "platform": "google",    "connected_account_id": "ba03bc4b-9f8c-4d3b-8e93-9628034c63cc"  }}

connection.location_disconnected

Attivazione: una scheda Google o Facebook viene scollegata da una sede.

Campo `data`	Tipo	Descrizione
`platform`	string	`google` o `facebook`.
`connected_account_id`	string	L'account connesso che è stato scollegato.

JSON

{  "event": "connection.location_disconnected",  "timestamp": "2026-08-25T14:35:02Z",  "account_id": 11073,  "location_id": "279381",  "data": {    "platform": "google",    "connected_account_id": "ba03bc4b-9f8c-4d3b-8e93-9628034c63cc"  }}

connection.reauth_required

Attivazione: le credenziali dell'account collegato sono state invalidate. Non verrà sincronizzato nulla per questa connessione finché qualcuno non la autorizzerà nuovamente.

Campo `data`	Tipo	Descrizione
`platform`	string	`google` o `facebook`.
`connected_account_id`	string	L'account collegato che richiede una nuova autorizzazione.
`reason`	string	Descrizione leggibile da una persona. Omessa quando la fonte non ne fornisce una.

JSON

{  "event": "connection.reauth_required",  "timestamp": "2026-08-25T14:40:18Z",  "account_id": 11073,  "location_id": "279381",  "data": {    "platform": "google",    "connected_account_id": "ba03bc4b-9f8c-4d3b-8e93-9628034c63cc",    "reason": "Google credentials are invalid. Please reconnect."  }}

connection.listing_inaccessible

Attivazione: l'account collegato non può più accedere alla scheda della sede. È un evento distinto da reauth_required: le credenziali possono essere ancora pienamente valide, ma l'accesso a quella specifica scheda è stato rimosso.

Campo `data`	Tipo	Descrizione
`platform`	string	`google` o `facebook`.
`connected_account_id`	string	L'account collegato che ha perso l'accesso.
`reason`	string	Descrizione leggibile da una persona. Omessa quando la fonte non ne fornisce una.

JSON

{  "event": "connection.listing_inaccessible",  "timestamp": "2026-08-25T14:42:55Z",  "account_id": 11073,  "location_id": "279381",  "data": {    "platform": "facebook",    "connected_account_id": "cf12de77-2211-4a09-b7c1-0a6f3b2e91aa",    "reason": "No longer has access to this listing."  }}

connection.google_verification_verified

Attivazione: il profilo Google Business Profile di una sede supera la verifica.

Campo `data`	Tipo	Descrizione
`platform`	string	Sempre `google`.
`connected_account_id`	null	Sempre `null` negli eventi di verifica.

JSON

{  "event": "connection.google_verification_verified",  "timestamp": "2026-08-25T14:50:00Z",  "account_id": 11073,  "location_id": "279381",  "data": {    "platform": "google",    "connected_account_id": null  }}

connection.google_verification_failed

Attivazione: una verifica di Google Business Profile raggiunge uno stato di errore definitivo. Nessuna chiamata REST avvia una verifica; lo stato stesso può essere letto, come indicato sopra.

Solo gli stati finali emettono un evento: VERIFIED genera l'evento _verified, mentre SUSPENDED o DUPLICATE (failure_type rejected) e ERROR_WHILE_FETCHING (transient) generano questo evento. Gli stati in corso (PENDING_VERIFICATION, UNDER_REVIEW, NOT_VERIFIED, NOT_CONNECTED) non producono alcun evento, quindi l'assenza di un evento non fornisce indicazioni. Leggi periodicamente googleVerificationStatus tramite una lettura della sede mentre una verifica è in corso.

Campo `data`	Tipo	Descrizione
`platform`	string	Sempre `google`.
`connected_account_id`	null	Sempre `null` negli eventi di verifica.
`failure_type`	string	`rejected` per un profilo sospeso o duplicato; `transient` quando non è stato possibile leggere i dati da Google. Ha senso riprovare solo per `transient`.
`reason`	string	Descrizione leggibile da una persona. Omessa quando la fonte non ne fornisce una.

JSON

{  "event": "connection.google_verification_failed",  "timestamp": "2026-08-25T14:52:31Z",  "account_id": 11073,  "location_id": "279381",  "data": {    "platform": "google",    "connected_account_id": null,    "failure_type": "rejected",    "reason": "This profile is suspended."  }}

Recensioni

Recensioni e risposte, insieme agli endpoint Recensioni, inclusi rispondi, modifica risposta e archivia risposta.

Le recensioni nella categoria Social vengono escluse e non vengono mai consegnate.

interaction.review

Attivazione: una recensione viene acquisita o modificata.

Campo `data.interaction`	Tipo	Descrizione
`id`	string	UUID dell'interazione. Identifica la recensione, non questa modifica: lo stesso id viene ricevuto nuovamente ogni volta che la recensione cambia. Usalo come chiave della riga; non usarlo mai per scartare una consegna successiva. Vedi duplicati e ordinamento.
`type`	string	`Review`.
`content`	string	Il testo della recensione. Può essere `null`.
`rating`	number	Valutazione in stelle. Può essere `null` per le fonti che non ne prevedono una.
`title`	string	Titolo della recensione, se previsto dalla fonte.
`author_name`	string	Nome visualizzato dell'autore della recensione.
`author_avatar`	string	URL dell'avatar dell'autore della recensione.
`date`	string	Data in formato ISO-8601 in cui la recensione è stata pubblicata sulla fonte.
`source`	string	La fonte da cui proviene, e.g. `google.com`, `facebook.com`.
`permalink`	string	Link alla recensione sulla fonte.
`category`	string	Categoria dell'interazione. `Social` viene escluso prima della consegna.
`interaction_status`	string	Stato dell'interazione nel flusso di lavoro.
`parent_id`	string	Sempre `null` per una recensione.
`interaction_request_id`	string	La richiesta a cui appartiene questa interazione. Può essere `null`.

JSON

{  "event": "interaction.review",  "timestamp": "2026-08-25T09:12:44Z",  "account_id": 11073,  "location_id": "279381",  "data": {    "interaction": {      "id": "6f8a1d20-3e11-4a55-9f7d-2b0c9e5a4471",      "type": "Review",      "content": "Friendly staff and no waiting.",      "rating": 5,      "title": null,      "author_name": "Dana R.",      "author_avatar": "https://lh3.googleusercontent.com/a/example",      "date": "2026-08-25T08:58:02Z",      "source": "google.com",      "permalink": "https://maps.google.com/example-review",      "category": "Review",      "interaction_status": "unread",      "parent_id": null,      "interaction_request_id": "3c1e9b74-88a2-4d0e-9c31-77a1f0be5d92"    }  }}

interaction.response

Attivazione: una risposta a una recensione viene pubblicata, modificata o archiviata. La struttura è la stessa di interaction.review, con due differenze: type è Response e parent_id fa riferimento alla recensione a cui si risponde.

Campo `data.interaction`	Tipo	Descrizione
`type`	string	`Response`.
`parent_id`	string	UUID della recensione a cui si risponde.
`content`	string	Il testo della risposta.
`rating`	number	Sempre `null` per una risposta.

Tutti gli altri campi elencati sotto interaction.review sono presenti con lo stesso significato.

JSON

{  "event": "interaction.response",  "timestamp": "2026-08-25T09:30:07Z",  "account_id": 11073,  "location_id": "279381",  "data": {    "interaction": {      "id": "b2d7c095-5f43-4e21-8a10-6d9c3f77e208",      "type": "Response",      "content": "Thanks Dana, see you next time!",      "rating": null,      "author_name": "Acme Dental Downtown",      "date": "2026-08-25T09:29:55Z",      "source": "google.com",      "permalink": "https://maps.google.com/example-review",      "category": "Review",      "interaction_status": "responded",      "parent_id": "6f8a1d20-3e11-4a55-9f7d-2b0c9e5a4471",      "interaction_request_id": "3c1e9b74-88a2-4d0e-9c31-77a1f0be5d92"    }  }}

Post

Post locali di Google Business Profile, insieme agli endpoint Post. L'ambito è la singola sede e location_id è una stringa numerica.

I quattro eventi condividono la stessa struttura data; i campi facoltativi variano. Tutti i campi facoltativi vengono omessi quando sono vuoti.

Campo `data`	Tipo	Descrizione
`post_id`	integer	Il post a cui appartiene questo elemento, identificato dall'id restituito dagli endpoint di creazione.
`post_item_id`	integer	L'elemento relativo alla singola sede. Un post destinato a 20 sedi produce 20 elementi e gli eventi sono emessi per ciascun elemento.
`post_type`	string	`STANDARD`, `EVENT` o `OFFER`.
`post_external_id`	string	Il nome della risorsa assegnato da Google al post. Assente finché Google non lo accetta.
`published_url`	string	Un URL consultabile nel browser. Di solito è assente: Google non lo restituisce in modo affidabile; usa `post_external_id` per la correlazione.
`rejection_reason`	string	Solo per `local_post.rejected`.

local_post.created

Attivazione: un elemento del post viene creato e messo in coda per l'invio a Google. Non è ancora pubblicato.

JSON

{  "event": "local_post.created",  "timestamp": "2026-08-25T11:02:00Z",  "account_id": 11073,  "location_id": "279381",  "data": {    "post_id": 88421,    "post_item_id": 5512309,    "post_type": "STANDARD"  }}

local_post.published

Attivazione: Google ha accettato il post, che ora è pubblicato.

JSON

{  "event": "local_post.published",  "timestamp": "2026-08-25T11:06:41Z",  "account_id": 11073,  "location_id": "279381",  "data": {    "post_id": 88421,    "post_item_id": 5512309,    "post_type": "STANDARD",    "post_external_id": "accounts/123/locations/456/localPosts/789"  }}

local_post.rejected

Attivazione: Google ha rifiutato il post oppure l'invio non è riuscito.

JSON

{  "event": "local_post.rejected",  "timestamp": "2026-08-25T11:07:15Z",  "account_id": 11073,  "location_id": "279381",  "data": {    "post_id": 88421,    "post_item_id": 5512310,    "post_type": "OFFER",    "rejection_reason": "Rejected"  }}

local_post.deleted

Attivazione: l'elemento del post viene eliminato.

JSON

{  "event": "local_post.deleted",  "timestamp": "2026-08-25T15:40:09Z",  "account_id": 11073,  "location_id": "279381",  "data": {    "post_id": 88421,    "post_item_id": 5512309,    "post_type": "STANDARD",    "post_external_id": "accounts/123/locations/456/localPosts/789"  }}

Pubblicazione sui social a livello di brand e ciclo di vita delle connessioni, insieme agli endpoint Social. Nove eventi: cinque per i post, quattro per le connessioni.

account_id e timestamp sono presenti come di consueto. Gli ID all'interno di data sono gli stessi UUID semplici usati dall'API REST, inviati come stringhe.

social_post.created

Attivazione: viene creato un post social. Solo alla creazione: la modifica di un post esistente non genera nuovamente l'evento.

Campo `data`	Tipo	Descrizione
`post_id`	string	L'UUID del post, lo stesso `socialPostId` restituito da create.
`social_profile_id`	string	Il brand a cui appartiene il post. `null` se il post non ne ha uno.
`status`	string	Lo stato del post al momento della creazione.
`created_by`	integer	L'utente che lo ha creato.
`platform_ids`	array of integer	Gli ID interni delle piattaforme a cui è destinato il post.

JSON

{  "event": "social_post.created",  "timestamp": "2026-09-28T14:02:11Z",  "account_id": 62570,  "location_id": null,  "data": {    "post_id": "c47a1e58-2b93-4f10-a6d7-58e0c9b12345",    "social_profile_id": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",    "status": "scheduled",    "created_by": 40122,    "platform_ids": [1, 2, 4]  }}

social_post.published

Attivazione: il post è stato pubblicato con esito completamente positivo. Questo evento viene emesso solo se l'operazione riesce completamente: almeno un canale ha pubblicato il post e nessun canale ha riscontrato errori. Una pubblicazione parziale non genera questo evento: in quel caso viene invece emesso social_post.failed.

Campo `data`	Tipo	Descrizione
`post_id`	string	L'UUID del post.
`social_profile_id`	string	Il brand a cui appartiene il post.
`status`	string	Lo stato del post.
`published_on`	string	L'istante in formato ISO-8601 in cui il post è stato pubblicato. `null` se non è stato registrato.
`items`	array of object	Una voce per canale; i campi sono descritti di seguito.
`items[].platform`	string	Nome della piattaforma, e.g. `instagram`.
`items[].social_platform_id`	integer	ID interno della piattaforma.
`items[].connected_account_id`	string	L'UUID della connessione tramite cui è stato pubblicato.
`items[].published_url`	string	L'URL pubblico dell'elemento pubblicato.
`items[].vendor_post_id`	string	L'ID assegnato dalla piattaforma all'elemento pubblicato.
`items[].status`	string	Lo stato di quel canale.

JSON

{  "event": "social_post.published",  "timestamp": "2026-10-02T13:30:07Z",  "account_id": 62570,  "location_id": null,  "data": {    "post_id": "c47a1e58-2b93-4f10-a6d7-58e0c9b12345",    "social_profile_id": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",    "status": "published",    "published_on": "2026-10-02T13:30:04",    "items": [      {        "platform": "instagram",        "social_platform_id": 2,        "connected_account_id": "b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7",        "published_url": "https://www.instagram.com/p/CxYz1234abc/",        "vendor_post_id": "18029384756012345",        "status": "success"      }    ]  }}

social_post.failed

Attivazione: la pubblicazione non è riuscita. Si tratta di un errore di consegna, distinto da un rifiuto editoriale. L'evento viene generato all'ultimo tentativo, quindi non viene emesso finché restano altri tentativi per il post.

items contiene solo i canali che hanno riscontrato errori, quindi un post pubblicato su due piattaforme ma non su una terza arriva qui con un solo elemento.

Campo `data`	Tipo	Descrizione
`post_id`	string	L'UUID del post.
`social_profile_id`	string	Il brand a cui appartiene il post.
`status`	string	Lo stato del post.
`items`	array of object	Una voce per ciascun canale su cui la pubblicazione non è riuscita; i campi sono descritti di seguito.
`items[].platform`	string	Nome della piattaforma.
`items[].social_platform_id`	integer	ID interno della piattaforma.
`items[].status`	string	Lo stato di quel canale.
`items[].reason`	string	Breve motivazione, troncata a 300 caratteri. Può essere `null`.
`items[].vendor_error`	string	Un messaggio di lunghezza limitata, sicuro da mostrare all'utente, derivato dall'errore della piattaforma. Non contiene mai il payload grezzo della piattaforma. Può essere `null`.

JSON

{  "event": "social_post.failed",  "timestamp": "2026-10-02T13:34:55Z",  "account_id": 62570,  "location_id": null,  "data": {    "post_id": "c47a1e58-2b93-4f10-a6d7-58e0c9b12345",    "social_profile_id": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",    "status": "failed",    "items": [      {        "platform": "linkedin",        "social_platform_id": 4,        "status": "error",        "reason": "Authorization expired",        "vendor_error": "The access token is no longer valid."      }    ]  }}

social_post.rejected

Attivazione: un flusso di approvazione ha rifiutato il post. Si tratta di un rifiuto editoriale, non di un errore di consegna: il post non ha mai raggiunto una piattaforma.

Campo `data`	Tipo	Descrizione
`post_id`	string	L'UUID del post.
`social_profile_id`	string	Il brand a cui appartiene il post.
`status`	string	Lo stato del post.
`rejection_reason`	string	Il commento del revisore. `null` se non ne ha lasciato uno.

JSON

{  "event": "social_post.rejected",  "timestamp": "2026-09-29T09:11:03Z",  "account_id": 62570,  "location_id": null,  "data": {    "post_id": "e08b2d97-6f14-4c22-b7a5-9d3e1f6c4a70",    "social_profile_id": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",    "status": "rejected",    "rejection_reason": "Please use the updated product name."  }}

social_post.deleted

Attivazione: il post è stato archiviato tramite POST /social/posts/cancel o dalla procedura di archiviazione pianificata. L'evento viene generato solo quando lo stato cambia effettivamente, quindi archiviare di nuovo un post già archiviato non genera alcun evento.

Campo `data`	Tipo	Descrizione
`post_id`	string	L'UUID del post.
`social_profile_id`	string	Il brand a cui appartiene il post.
`status`	string	Lo stato del post.
`archived_at`	string	L'istante in formato ISO-8601 in cui il post è stato archiviato. `null` se non è stato registrato.

JSON

{  "event": "social_post.deleted",  "timestamp": "2026-09-30T16:20:41Z",  "account_id": 62570,  "location_id": null,  "data": {    "post_id": "e08b2d97-6f14-4c22-b7a5-9d3e1f6c4a70",    "social_profile_id": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",    "status": "archived",    "archived_at": "2026-09-30T16:20:39"  }}

social_connection.connected

Attivazione: un canale del brand è diventato attivo, tramite una prima connessione o la riconnessione di un canale precedentemente archiviato. is_reconnect distingue i due casi.

Campo `data`	Tipo	Descrizione
`social_profile_id`	string	Il brand a cui è associato il canale.
`connected_account_id`	string	L'UUID della connessione, il valore `id` restituito dall'elenco delle connessioni.
`platform`	string	Nome della piattaforma, e.g. `instagram`.
`display_name`	string	Il nome visualizzato del canale. Può essere `null`.
`is_reconnect`	boolean	`false` alla prima connessione, `true` quando un canale precedentemente archiviato è tornato attivo.
`listing_connected_account_id`	string	Presente solo quando il canale è collegato anche a un account connesso di Listings. Altrimenti viene omesso.

JSON

{  "event": "social_connection.connected",  "timestamp": "2026-09-27T11:05:22Z",  "account_id": 62570,  "location_id": null,  "data": {    "social_profile_id": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",    "connected_account_id": "b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7",    "platform": "instagram",    "display_name": "Jenny Home",    "is_reconnect": false  }}

social_connection.disconnected

Attivazione: il canale è stato rimosso intenzionalmente con una chiamata a disconnect. L'evento viene emesso solo quando il canale è stato effettivamente archiviato, quindi una disconnessione non riuscita non genera un falso evento.

Campo `data`	Tipo	Descrizione
`social_profile_id`	string	Il brand a cui era associato il canale.
`connected_account_id`	string	L'UUID della connessione.
`platform`	string	Nome della piattaforma.
`display_name`	string	Il nome visualizzato del canale. Può essere `null`.

JSON

{  "event": "social_connection.disconnected",  "timestamp": "2026-10-04T08:47:10Z",  "account_id": 62570,  "location_id": null,  "data": {    "social_profile_id": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",    "connected_account_id": "b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7",    "platform": "instagram",    "display_name": "Jenny Home"  }}

social_connection.archived

Attivazione: la connessione al canale è stata persa involontariamente: la piattaforma ha invalidato il token oppure una procedura di riconciliazione ha rilevato che il canale non era più raggiungibile. Nessuno ha richiesto questa disconnessione, ed è questo che la distingue da disconnected.

Campo `data`	Tipo	Descrizione
`social_profile_id`	string	Il brand a cui era associato il canale.
`connected_account_id`	string	L'UUID della connessione.
`platform`	string	Nome della piattaforma.
`display_name`	string	Il nome visualizzato del canale. Può essere `null`.
`reason`	string	Il motivo per cui la connessione è stata persa. Può essere `null`.

JSON

{  "event": "social_connection.archived",  "timestamp": "2026-10-06T02:15:33Z",  "account_id": 62570,  "location_id": null,  "data": {    "social_profile_id": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",    "connected_account_id": "2d4e6f80-1c33-4b7a-8e05-9a1b2c3d4e5f",    "platform": "facebook",    "display_name": "Jenny Home & Co.",    "reason": "Access token has been invalidated by the platform."  }}

Analisi delle recensioni

Riepiloghi programmati delle recensioni, un evento per sede per periodo.

Entrambi gli eventi condividono la stessa struttura di data:

Campo di `data`	Tipo	Descrizione
`period`	string	Inizio del periodo, `YYYY-MM-DD`.
`granularity`	string	`daily` o `weekly`.
`total_reviews`	integer	Numero totale di recensioni ricevute dalla sede dall'inizio.
`new_reviews_in_period`	integer	Recensioni ricevute durante questo periodo.
`average_rating`	number	Valutazione media per questo periodo, con 4 cifre decimali. `0.0` se non ci sono state recensioni.
`previous_average_rating`	number	Valutazione media per il periodo precedente. `0.0` se non ci sono dati precedenti.

Una sede senza attività nel periodo non genera alcun evento, ma non ne ricevi nemmeno per una sede la cui istantanea non è mai arrivata. L'assenza di un'istantanea è ambigua e, per questa famiglia di eventi, l'interpretazione innocua è la meno probabile. Può significare: nessuna attività; una consegna non riuscita o scaduta per timeout (è previsto un solo tentativo, senza ulteriori tentativi); una consegna disabilitata perché l'account non dispone dell'abilitazione ai webhook, non ha un URL configurato, non è verificato o è bloccato; oppure, come è più probabile in questo caso, il limite al minuto che scarta parte della raffica come rate_limited.

Non registrare mai uno zero basandoti sull'assenza di un'istantanea. Verifica i dati tramite GET /locations/{locationId}/review-analytics-overview per lo stesso periodo e, se anche quella lettura non riesce, indica il periodo come non disponibile anziché come zero.

review_analytics.daily_snapshot

Attivazione: il processo di riepilogo giornaliero, una volta per sede al giorno.

JSON

{  "event": "review_analytics.daily_snapshot",  "timestamp": "2026-08-25T02:00:00Z",  "account_id": 11073,  "location_id": "279381",  "data": {    "period": "2026-08-24",    "granularity": "daily",    "total_reviews": 1240,    "new_reviews_in_period": 3,    "average_rating": 4.6667,    "previous_average_rating": 5.0  }}

review_analytics.weekly_snapshot

Attivazione: il processo di riepilogo settimanale, una volta per sede alla settimana. period è il primo giorno della settimana riepilogata.

JSON

{  "event": "review_analytics.weekly_snapshot",  "timestamp": "2026-08-24T02:00:00Z",  "account_id": 11073,  "location_id": "279381",  "data": {    "period": "2026-08-17",    "granularity": "weekly",    "total_reviews": 1237,    "new_reviews_in_period": 18,    "average_rating": 4.6123,    "previous_average_rating": 4.5901  }}

Eventi che potresti ricevere ma su cui non dovresti basare la tua integrazione

La piattaforma genera altre famiglie di eventi: campagne di recensioni, posizionamenti, promozioni di post sui social, modifiche dello stato degli account pubblicitari sui social, idee per post generate dall'IA e proprietà di Google Business Profile. Non hanno un endpoint REST pubblicato nella Listings API, non sono documentate qui e le loro strutture non sono coperte da alcuna garanzia di compatibilità. Poiché esiste un solo URL e non è prevista una sottoscrizione per singolo evento, il tuo gestore dovrebbe ignorare qualsiasi event che non riconosce e restituire comunque 200.