Visão geral dos webhooks

Como a Listings API envia eventos da conta ao seu servidor, quais eventos existem e as cinco verificações pelas quais cada entrega deve passar.

Consultar uma API repetidamente para descobrir se algo mudou é custoso e sempre traz algum atraso. Os webhooks invertem esse processo: quando algo acontece na sua conta (uma avaliação é recebida, um local é editado, uma publicação do Google Business entra no ar), a Listings API envia uma requisição HTTP POST com um corpo JSON para uma URL que você controla, em segundos.

Há uma única URL de webhooks por conta e nenhuma assinatura por evento. Se os webhooks estiverem habilitados na sua conta e seu endpoint estiver verificado, todos os eventos listados nesta página serão entregues a essa mesma URL. Use o campo event para definir o tratamento de cada evento e ignore o que você não precisar.

O fluxo de entrega

O que você pode receber

Dezoito eventos distribuídos em seis famílias. Cada um corresponde a um recurso que você já gerencia pela API REST, de modo que o webhook informa quando e o endpoint informa o quê.

As tabelas completas de campos e os exemplos de payload estão na referência de eventos.

Fora do escopo

A plataforma emite outras famílias de eventos que a Listings API não documenta nem oferece suporte, pois elas não têm um endpoint REST publicado aqui. Elas estão listadas para que nada pareça ter sido omitido por engano:

• Campanhas de avaliações: campaign.*
• Classificações: rankings.*
• Publicações e impulsionamentos no Social: social_post.*
• Conexões do Social: social_connection.*
• Ideias de publicações geradas por IA: idea.*, idea_series.*, idea_pipeline.*, idea_image.*
• Propriedade do Google Business Profile: gbp_ownership.*

Duas ressalvas para ler antes de implementar

Condições para a entrega

A entrega depende de cinco condições, verificadas nessa ordem. A primeira condição não atendida interrompe a entrega; as condições seguintes nunca são verificadas.

Planos e limites

Webhooks são uma permissão incluída em todos os planos: Launch, Growth e Enterprise. O período de teste usa o plano que você escolheu, portanto, contas em teste têm webhooks desde o primeiro dia, com os limites desse plano. A permissão está vinculada ao seu plano, portanto, ela é concedida ou removida como parte de uma mudança de plano, em vez de imediatamente: espere que ela entre em vigor na próxima mudança de plano ou sincronização do cadastro, e não no momento em que você clicar para fazer o upgrade. A página Webhooks do painel mostra sua permissão e seus limites atuais.

As entregas também são contabilizadas em relação a um limite por minuto e a um limite por dia, ambos definidos pelo seu plano.

Os limites de webhooks correspondem aos limites de requisições à API do seu plano: a cota de eventos que enviamos a você é igual à cota de requisições que você nos envia.

Um limite só começa a ser aplicado à sua conta depois que os limites do seu plano são sincronizados com o fluxo de entrega. Até que isso aconteça, não há limite a verificar, portanto, nada é contabilizado e nada é descartado. Assim, uma conta recém-criada pode receber entregas sem contabilização antes que o limite do plano seja aplicado. Não interprete a ausência de rate_limited como prova de que você está abaixo do limite.

Como a contabilização funciona:

• Duas janelas fixas independentes: uma por minuto e outra por dia. Não há janela por hora para webhooks. (O limitador de taxa de requisições é um sistema separado, com janelas diferentes; os dois não compartilham uma cota.)
• As janelas seguem os intervalos do calendário, não são deslizantes: o contador por minuto é zerado na virada de cada minuto, e o contador diário, na virada do dia em UTC.
• Quando o limite é excedido, o evento é descartado. Ele não é colocado em uma fila, não é adiado e não há nova tentativa: não existe fila de novas tentativas em nenhuma etapa do fluxo de saída, nem um chamador ao qual retornar 429. A tentativa é registrada com o status de entrega rate_limited para que a perda fique visível, em vez de passar despercebida.
• O limitador permite a entrega em caso de falha. Se o próprio limitador não conseguir responder, a entrega é realizada em vez de ser descartada. Você nunca perderá um evento por uma falha na contabilização.

O único controle de volume integrado no lado que produz os eventos é um debounce em profile.updated: no máximo uma entrega por local a cada 60 segundos, no início da janela. Edições feitas em rápida sequência no mesmo local são agrupadas em um único evento, e os changed_fields que você recebe descrevem apenas a edição que abriu a janela. Nenhum outro evento está sujeito a debounce.

Como a entrega ocorre no início da janela, ela chega a você no começo do intervalo de 60 segundos: uma consulta aos dados acionada pela chegada do evento vê apenas a primeira edição. Agende uma segunda consulta após o fechamento da janela, pelo menos 60 segundos após o evento, e também reconcilie os locais periodicamente, pois o evento em si tem apenas uma tentativa de entrega, sem novas tentativas. Consulte como se recuperar da perda de um evento.

Configuração

1. Disponibilize um endpoint HTTPS. Ele deve ter um endereço que possa ser resolvido publicamente e um certificado válido, aceitar POST e retornar 2xx em menos de 5 segundos. Endereços privados e internos (loopback, RFC-1918, link-local e IPs de metadados de nuvem) são recusados.
2. Salve a URL dos seus webhooks na página Webhooks do painel. Uma URL por conta, para todos os eventos.
3. Gere um segredo de assinatura e armazene-o no seu servidor. Ele é exibido uma única vez. A partir desse momento, as entregas são assinadas e a verificação é obrigatória.
4. Verifique o endpoint. A plataforma envia um desafio assinado; seu endpoint responde com um HMAC do nonce em formato hexadecimal. Se a verificação for bem-sucedida, o endpoint passa a ser considerado verificado e as entregas começam. Consulte assinaturas e verificação para obter o contrato exato e o código funcional.
5. Processe os eventos. Confira a assinatura, coloque o payload na fila e retorne 200. Execute o processamento efetivo fora do fluxo da requisição. Consulte comportamento de entrega para obter informações sobre o tempo limite, a política de tentativa única e o que esperar em relação a duplicatas e à ordem dos eventos.

Próximos passos

• Assinaturas e verificação: o cabeçalho X-ListingsAPI-Signature, a regra para o corpo bruto da requisição e o handshake.
• Comportamento de entrega: o payload padrão, o tempo limite de 5 segundos, por que não há novas tentativas e todos os status de entrega.
• Referência de eventos: todos os 18 eventos, campo por campo.