Panoramica dei webhook

Come la Listings API invia gli eventi dell’account al tuo server, quali eventi esistono e i cinque controlli che ogni invio deve superare.

Interrogare periodicamente un'API per scoprire se qualcosa è cambiato è costoso e comporta sempre un certo ritardo. I webhook invertono il meccanismo: quando accade qualcosa nel tuo account (arriva una recensione, viene modificata una sede, viene pubblicato un post su Google Business), la Listings API invia entro pochi secondi una richiesta HTTP POST con un corpo JSON a un URL sotto il tuo controllo.

È previsto un solo URL per i webhook per account e non è possibile iscriversi ai singoli eventi. Se i webhook sono abilitati per il tuo account e il tuo endpoint è verificato, ogni evento elencato in questa pagina viene inviato a quell'unico URL. Gestisci gli eventi in base al campo event e ignora quelli che non ti servono.

La pipeline di consegna

Cosa puoi ricevere

18 eventi suddivisi in 6 famiglie. Ciascuno corrisponde a una risorsa che gestisci già tramite l'API REST, quindi il webhook ti indica quando avviene una modifica e l'endpoint ti indica cosa è cambiato.

Le tabelle complete dei campi e i payload di esempio si trovano nella documentazione di riferimento degli eventi.

Fuori ambito

La piattaforma emette altre famiglie di eventi che la Listings API non documenta né supporta, perché non hanno un endpoint REST pubblicato qui. Sono elencate per chiarire che non si tratta di omissioni accidentali:

• Campagne di recensioni: campaign.*
• Posizionamenti: rankings.*
• Post e promozioni in Social: social_post.*
• Collegamenti a Social: social_connection.*
• Idee per post generate dall'IA: idea.*, idea_series.*, idea_pipeline.*, idea_image.*
• Proprietà di Google Business Profile: gbp_ownership.*

2 precisazioni da leggere prima di iniziare l'implementazione

Controlli per l'invio

L'invio dipende da cinque condizioni, verificate nell'ordine indicato. Il primo controllo che fallisce interrompe l'invio; i controlli successivi non vengono mai eseguiti.

Piani e limiti

I webhook sono una funzionalità inclusa in ogni piano: Launch, Growth ed Enterprise. La prova si svolge sul piano che hai scelto, quindi gli account in prova dispongono dei webhook dal primo giorno, con i limiti di quel piano. L'abilitazione è legata al tuo piano, quindi viene concessa o rimossa nell'ambito di un cambio di piano anziché immediatamente: aspettati che diventi effettiva al prossimo cambio di piano o alla sincronizzazione della registrazione, non nel momento in cui fai clic per passare a un piano superiore. La pagina Webhooks della dashboard mostra l'abilitazione e i limiti attualmente in vigore.

Gli invii vengono inoltre conteggiati rispetto a un limite al minuto e a un limite al giorno, entrambi definiti dal tuo piano.

I limiti dei webhook corrispondono ai limiti delle richieste API del tuo piano: il numero di eventi che possiamo inviarti equivale al numero di richieste che puoi inviarci.

Un limite inizia ad applicarsi al tuo account solo dopo che i limiti del tuo piano sono stati sincronizzati con il sistema di invio. Fino a quel momento non esiste alcun limite da verificare, quindi nulla viene conteggiato e nulla viene scartato. Un account appena creato può quindi ricevere invii senza conteggio prima che venga applicato il limite del suo piano. Non interpretare l'assenza di rate_limited come prova del fatto che non hai superato il limite.

Come funziona il conteggio:

• Due finestre fisse indipendenti: una al minuto, una al giorno. Non esiste una finestra oraria per i webhook. (Il limitatore della frequenza delle richieste è un sistema diverso con finestre diverse; i due sistemi non condividono la stessa quota.)
• Le finestre seguono gli intervalli di calendario, non sono mobili: il contatore dei minuti si azzera all'inizio di ogni minuto, quello giornaliero all'inizio di ogni giorno UTC.
• Quando il limite viene superato, l'evento viene scartato. Non viene messo in coda, ritardato o ritentato: non esiste alcuna coda per i nuovi tentativi lungo l'intero percorso di invio e non c'è alcun chiamante a cui restituire un 429. Il tentativo viene registrato con lo stato di invio rate_limited, così la perdita è visibile anziché passare inosservata.
• In caso di errore, il limitatore consente l'invio. Se il limitatore stesso non riesce a rispondere, l'invio viene eseguito anziché scartato. Non perderai mai un evento a causa di un malfunzionamento del contatore.

L'unico controllo del volume integrato sul lato che genera gli eventi è un debounce su profile.updated: al massimo un invio per sede ogni 60 secondi, all'inizio della finestra. Le modifiche ravvicinate alla stessa sede vengono raggruppate in un unico evento e i changed_fields che ricevi descrivono solo la modifica che ha aperto la finestra. Il debounce non viene applicato a nient'altro.

Poiché l'invio avviene all'inizio della finestra, ti arriva all'inizio dell'intervallo di 60 secondi: una rilettura attivata dal suo arrivo vede solo la prima modifica. Pianifica una seconda rilettura dopo la chiusura della finestra, almeno 60 secondi dopo l'evento, ed esegui anche una riconciliazione periodica delle sedi, poiché per l'evento viene effettuato un solo tentativo di invio, senza nuovi tentativi. Consulta come recuperare un evento perso.

Configurazione

1. Configura un endpoint HTTPS. Deve avere un indirizzo risolvibile pubblicamente e un certificato valido, accettare POST e rispondere con 2xx in meno di 5 secondi. Gli indirizzi privati e interni (loopback, RFC-1918, link-local, indirizzi IP dei servizi di metadati cloud) vengono rifiutati.
2. Salva l'URL dei webhook nella pagina Webhooks della dashboard. Un solo URL per account, per tutti gli eventi.
3. Genera un segreto di firma e salvalo sul tuo server. Viene mostrato una sola volta. Da questo momento le consegne sono firmate e la verifica è obbligatoria.
4. Verifica l'endpoint. La piattaforma invia una richiesta di verifica firmata; il tuo endpoint risponde con un HMAC del nonce in formato esadecimale. Se la verifica riesce, l'endpoint passa allo stato verificato e le consegne iniziano. Consulta firme e verifica per le specifiche esatte e il codice funzionante.
5. Gestisci gli eventi. Verifica la firma, inserisci il payload in coda e restituisci 200. Esegui l'elaborazione effettiva al di fuori della gestione della richiesta. Consulta comportamento delle consegne per il timeout, la regola del singolo tentativo e cosa aspettarti riguardo a duplicati e ordine.

Prossimi passi

• Firme e verifica: l'intestazione X-ListingsAPI-Signature, la regola sul corpo della richiesta non elaborato e l'handshake.
• Comportamento delle consegne: il payload standard, il timeout di 5 secondi, il motivo per cui non sono previsti nuovi tentativi e tutti gli stati di consegna.
• Riferimento degli eventi: tutti i 18 eventi, campo per campo.