Descripción general de los webhooks

Cómo Listings API envía eventos de la cuenta a tu servidor, qué eventos existen y los cinco controles que debe superar cada entrega.

Consultar periódicamente una API para detectar cambios es costoso y siempre implica cierto retraso. Los webhooks invierten este proceso: cuando ocurre algo en tu cuenta (llega una reseña, se edita una ubicación, se publica una entrada de Google Business), Listings API envía una solicitud HTTP POST con un cuerpo JSON a una URL que controlas, en cuestión de segundos.

Hay una URL de webhooks por cuenta y no hay suscripciones por evento. Si los webhooks están habilitados para tu cuenta y tu endpoint está verificado, todos los eventos enumerados en esta página se envían a esa única URL. Usa el campo event para decidir cómo procesar cada evento e ignora lo que no necesites.

El proceso de entrega

Todos los eventos siguen el mismo proceso. Las cinco condiciones se comprueban en orden y, si alguna no se cumple, no se realiza ninguna solicitud HTTP, aunque el intento queda registrado.

Qué puedes recibir

Dieciocho eventos distribuidos en seis familias. Cada uno corresponde a un recurso que ya gestionas mediante la API REST, por lo que el webhook te indica cuándo y el endpoint te indica qué.

Familia	Eventos	Recurso REST relacionado
`listing.submission`	1	Fichas
`profile.*`	3: creación, actualización, eliminación	Ubicaciones
`connection.*`	6: conexión, desconexión, reautenticación, inaccesibilidad, 2 × verificación de Google	Cuentas conectadas
`interaction.*`	2: reseña, respuesta	Reseñas
`local_post.*`	4: creación, publicación, rechazo, eliminación	Publicaciones
`review_analytics.*`	2: instantáneas diaria y semanal	Analítica

Las tablas completas de campos y los ejemplos de cuerpos de eventos se encuentran en la referencia de eventos.

Fuera del alcance

La plataforma emite otras familias de eventos que Listings API no documenta ni admite porque no tienen ningún endpoint REST publicado aquí. Se enumeran para que no parezca que se han omitido por accidente:

Campañas de reseñas: campaign.*
Posicionamiento: rankings.*
Publicaciones y promociones de Social: social_post.*
Conexiones de Social: social_connection.*
Ideas de publicaciones generadas por IA: idea.*, idea_series.*, idea_pipeline.*, idea_image.*
Propiedad de Google Business Profile: gbp_ownership.*

Dos consideraciones que debes leer antes de empezar a desarrollar

Controles de entrega

La entrega depende de cinco controles, que se comprueban en ese orden. El primer control que falla detiene la entrega; los controles posteriores no llegan a ejecutarse.

#	Control	Si falla
1	Tu plan incluye webhooks. Una función habilitada en la cuenta.	No se registra nada. El evento simplemente no se te envía.
2	Hay una URL de webhooks configurada en la cuenta.	No se registra nada.
3	El endpoint ha superado la verificación: solo se exige cuando existe un secreto de firma.	Se registra como `endpoint_unverified`.
4	La URL se resuelve a una dirección pública (HTTPS, host con resolución pública).	Se registra como `blocked_url`.
5	Estás dentro del límite de webhooks de tu plan.	Se registra como `rate_limited`. El evento se descarta, no se pone en cola.

Planes y límites

Los webhooks están incluidos en todos los planes: Launch, Growth y Enterprise. El período de prueba utiliza el plan que elegiste, por lo que las cuentas de prueba disponen de webhooks desde el primer día con los límites de ese plan. La habilitación está vinculada a tu plan, por lo que se concede o se retira como parte de un cambio de plan, en lugar de aplicarse al instante: cuenta con que surta efecto en el próximo cambio de plan o en la sincronización del registro, no en el momento en que hagas clic para cambiar a un plan superior. La página Webhooks del panel muestra si tienes habilitada la función y cuáles son tus límites actuales.

Las entregas también se contabilizan con respecto a un límite por minuto y otro por día, ambos definidos por tu plan.

Plan	Por minuto	Por día
Launch	10	7,200
Growth	50	36,000
Enterprise	Sin límite	Sin límite

Los límites de webhooks coinciden con los límites de solicitudes a la API de tu plan: la cuota de eventos que te enviamos es igual a la cuota de solicitudes que nos envías.

Un límite solo empieza a aplicarse a tu cuenta cuando los límites de tu plan se han sincronizado con el proceso de entrega. Hasta entonces, no hay ningún límite que comprobar, por lo que no se contabiliza ni se descarta nada. Por tanto, una cuenta recién creada puede recibir entregas sin contabilizar antes de que se aplique el límite de su plan. No interpretes la ausencia de rate_limited como prueba de que estás por debajo del límite.

Cómo funciona el contador:

Dos intervalos fijos independientes: uno por minuto y otro por día. No hay ningún intervalo por hora para los webhooks. (El limitador de frecuencia de solicitudes es un sistema distinto con intervalos diferentes; ambos sistemas tienen cuotas independientes.)
Los intervalos se ajustan al calendario, no son deslizantes: el contador por minuto se reinicia al comenzar cada minuto y el contador diario, al comenzar cada día en UTC.
Si se supera el límite, el evento se descarta. No se pone en cola, no se retrasa ni se reintenta: no hay ninguna cola de reintentos en todo el proceso de salida, ni ningún solicitante al que devolver un 429. El intento se registra con el estado de entrega rate_limited para que la pérdida sea visible y no pase inadvertida.
Si el limitador falla, permite la entrega. Si el propio limitador no puede responder, la entrega se realiza en lugar de descartarse. Nunca perderás un evento por un fallo del contador.

El único control de volumen integrado en el lado que produce los eventos es un mecanismo de debounce en profile.updated: como máximo, una entrega por ubicación cada 60 segundos, al inicio del intervalo. Las modificaciones rápidas de una misma ubicación se agrupan en un único evento, y los changed_fields que recibes describen únicamente la modificación que abrió el intervalo. No se aplica debounce a nada más.

Como la entrega se realiza al inicio del intervalo, te llega al comienzo de los 60 segundos: una consulta de los datos activada por su llegada solo verá la primera modificación. Programa una segunda consulta una vez cerrado el intervalo, al menos 60 segundos después del evento, y realiza también una conciliación periódica de las ubicaciones, ya que el evento solo tiene un intento de entrega y no se reintenta. Consulta cómo recuperarte de un evento perdido.

Configuración

Configura un endpoint HTTPS. Su dirección debe poder resolverse públicamente, debe tener un certificado válido, aceptar POST y responder con 2xx en menos de 5 segundos. Se rechazan las direcciones privadas e internas (loopback, RFC-1918, link-local y direcciones IP de metadatos de la nube).
Guarda tu URL de webhooks en la página Webhooks del panel. Una URL por cuenta para todos los eventos.
Genera un secreto de firma y guárdalo en tu servidor. Se muestra una sola vez. A partir de este momento, las entregas se firman y la verificación es obligatoria.
Verifica el endpoint. La plataforma envía un desafío firmado; tu endpoint responde con un HMAC del nonce en formato hexadecimal. Si la verificación se completa correctamente, el endpoint pasa a estar verificado y comienzan las entregas. Consulta firmas y verificación para conocer el contrato exacto y ver código funcional.
Procesa los eventos. Verifica la firma, añade el payload a una cola y devuelve 200. Realiza el procesamiento efectivo fuera del flujo de la solicitud. Consulta comportamiento de las entregas para conocer el tiempo de espera, la política de un único intento y el comportamiento previsto en cuanto a duplicados y orden.

Próximos pasos

Firmas y verificación: la cabecera X-ListingsAPI-Signature, la regla sobre el cuerpo sin procesar y el intercambio de verificación.
Comportamiento de las entregas: el payload estándar, el tiempo de espera de 5 segundos, por qué no hay reintentos y todos los estados de entrega.
Referencia de eventos: los 18 eventos, campo por campo.