Listings APIListings API
Oturum aç

Teslimat davranışı

Standart veri yükü, 5 saniyelik süre sınırı, neden yeniden deneme yapılmadığı ve her teslimat durumunun anlamı.

Webhook iletimi bilinçli olarak basit tutulmuştur ve bu basitliğin alıcı tarafında sonuçları vardır: tek HTTP denemesi, beş saniye, yeniden deneme yok. İşleyicinizin istek sırasında ne kadar işlem yapacağına karar vermeden önce bu sayfayı okuyun.

Standart veri yükü

listing.submission dışındaki tüm olaylar aynı üst düzey yapıda gelir ve olaya özgü alanlar data altında yer alır.

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"  }}
AlanTürNotlar
eventstringNoktalarla ayrılmış olay adı. İşlem akışını bu değere göre dallandırın.
timestampstringISO-8601 UTC biçimindedir; temel alınan değişiklik gerçekleştiğinde değil, iletim hazırlandığında zaman damgası eklenir.
account_idintegerOlayın ait olduğu hesap.
location_idstringSayısal bir dize: 279381 değil, "279381". interaction.* için tür dönüşümü yapılmaz; aşağıdaki istisnaya bakın.
dataobjectOlaya özgü alanlar. Olay başvurusunda her olay için ayrı ayrı belgelenmiştir.
agency_account_idintegerHesap bir üst ajans hesabı tarafından yönetiliyorsa bulunur; aksi takdirde bulunmaz.

data içindeki isteğe bağlı alanlar boş olduğunda null olarak gönderilmez, veri yüküne dahil edilmez. Kodunuzu bu durumlara hazırlıklı yazın: eksik bir anahtarı ve açıkça belirtilmiş bir null değerini aynı şekilde ele alın ve isteğe bağlı olarak belgelenmiş bir anahtarın bulunacağını asla varsaymayın.

İki istisna

5 saniyelik süre sınırı

Her iletim, 5 saniyelik bağlantı zaman aşımı ve 5 saniyelik okuma zaman aşımı olan tek bir POST işlemidir. Uç noktanız zamanında yanıt vermezse deneme sonlandırılır ve timeout olarak kaydedilir.

Bu süre sınırı, işleyicinizin tamamını kapsar. Tek güvenli tasarım şöyledir:

  1. İmzayı doğrulayın.
  2. Veri yükünü kalıcı bir yere yazın: bir kuyruk, tablo veya günlük.
  3. 200 döndürün.

Diğer tüm işlemler (veri zenginleştirme, birden fazla hedefe dağıtım, REST API'ye geri çağrı yapma ve üçüncü taraflarla etkileşim kuran her türlü işlem) bu kuyruktan sonra yapılmalıdır.

Yeniden deneme yapılmaz

Bir iletim tam olarak bir kez denenir. Giderek artan bekleme süreleriyle yeniden deneme, yeniden deneme kuyruğu veya başarısız iletiler için bir kuyruk yoktur. Uç noktanız iki dakika boyunca çalışmazsa bu iki dakikada tetiklenen olaylar kaybolur. Daha sonra ulaşmazlar.

Açıkça belirtilmesi gereken iki sonuç:

  • Yönlendirmeler izlenmez. Yönlendirmeler tamamen devre dışıdır; dolayısıyla uç noktanızın döndürdüğü 301 veya 302, başarısız bir iletim olarak kaydedilir ve ikinci bir URL'ye yönlendirme izlenmez. Webhook URL'nizi nihai URL olarak yapılandırın. Birçok web sunucusunun varsayılan olarak eklediği, yalın alan adından www adresine yapılan yönlendirmelere ve sona eğik çizgi ekleyen yönlendirmelere dikkat edin.
  • Yalnızca 2xx döndürülürse iletim başarılı sayılır. 3xx, 4xx ve 5xx yanıtlarının tümü başarısızlık olarak kaydedilir.

Yinelenen olaylar ve sıralama

  • Aynı olayı iki kez ve iki farklı değişiklik için aynı id değerini alabilirsiniz. data içindeki tanımlayıcılar (bir etkileşim id değeri, bir gönderi öğesi id değeri, bir bağlı hesap id değeri) değişikliği değil, kaynağı tanımlar. interaction.review, yorum her değiştiğinde aynı etkileşim id değeriyle yeniden tetiklenir ve hiçbir olay verisi sürüm veya güncellenme zamanı alanı içermez; bu nedenle id + event temelinde olayları kalıcı olarak engelleyen bir işleyici, gerçek düzenlemeleri sessizce yok sayar. Bunun yerine birebir aynı olayları tespit edin: ham gövde baytlarının özetini hesaplayın ve aynı özetin kısa ve sınırlı bir süre içinde (sonsuza kadar değil, birkaç dakika boyunca) tekrarını yok sayın. Aynı id değerine sahip farklı bir gövde, yinelenen bir olay değil, yeni bir değişikliktir. Ardından kaynağı REST API üzerinden yeniden okuyun ve bu okumanın sonucunu esas alın; yazma işlemini atlamak yerine kaynak id değerini yazma işleminin anahtarı olarak kullanın.
  • Sıralama garanti edilmez ve timestamp bunu düzeltmez. Olaylar birbirinden bağımsız birkaç kanaldan gelir ve geldikleri sırayla iletilir; bu nedenle bir local_post.published, önce gelmesini beklediğiniz local_post.created olayından önce gelebilir. Aynı kaynaktaki iki değişikliği timestamp değerine göre sıralamayın: bu zaman damgası değişikliğin gerçekleştiği anda değil, teslimat hazırlanırken eklenir ve olay verisinin hiçbir yerinde sürüm veya sıra numarası bulunmaz. Sıralama önemli olduğunda kaynağı yeniden okuyun ve API'nin döndürdüğü veriyi kullanın.
  • profile.updated için yinelenen olaylar bastırılarak konum başına her 60 saniyede tek teslimat yapılır; teslimat sürenin başında gerçekleşir. Bu işlem geciktirme değil, olayları gerçekten tek olaya indirme işlemidir: ilk düzenleme süreyi başlatır ve iletilir, bu süre içindeki her düzenleme atılır ve hiçbir zaman ulaşmaz; changed_fields ise yalnızca süreyi başlatan düzenlemeyi açıklar. Dolayısıyla olay size sürenin başında ulaşır; bu nedenle olayın ulaşmasıyla tetiklenen yeniden okuma yalnızca ilk düzenlemeyi görebilir. Olaydan en az 60 saniye sonra, süre sona erdiğinde ikinci bir yeniden okuma planlayın ve konumları ayrıca zamanlanmış aralıklarla karşılaştırıp eşitleyin; çünkü bildirimin kendisi de kaybolabilir: tek deneme yapılır, yeniden deneme yapılmaz. Başka hiçbir olay için bu bastırma uygulanmaz.

Kaçırılan bir olayın ardından verileri kurtarma

Yeniden deneme veya olayları yeniden iletme yoktur; bu nedenle her olay grubu için gerektiğinde başvurabileceğiniz, sonucu esas alınacak bir okuma işlemi gerekir. Verileri yalnızca bir sorun var gibi göründüğünde değil, düzenli aralıklarla karşılaştırıp eşitleyin.

Olay grubuYeniden okuma yöntemiÖnerilen aralıkOkumayla kurtarılamayan bilgiler
listing.submissionGET /locations/{locationId}/listings/premium, bir kez listingType=premium ile ve bir kez additional ile: olayın bildirdiği site başına syncStatus ve listingUrl.Her konum için günlük olarak ve toplu konum düzenlemesinden sonra.Eski biçimdeki olay verisinde ne timestamp ne de account_id bulunur; bu nedenle kaçırılan bir olayın zamanı veya hangi hesaba ait olduğu belirlenemez. Bir incomplete gönderimindeki error_message, hiçbir okuma işlemiyle sunulmaz.
profile.*GET /locations, GET /locations/search veya GET /locations-by-ids. Her konumdaki updatedAt, hangi konumların değiştiğini gösterir.Saatlik olarak ve ayrıca yukarıda açıklanan süre sonu yeniden okumasıyla.source (user / api / bulk_edit) ve changed_fields: okuma işlemi mevcut durumu gösterir, kimin neyi değiştirdiğini hiçbir zaman göstermez. 60 saniyelik bastırma süresi içinde elenen düzenlemeler hiçbir iz bırakmaz ve silinen bir konumun silinmeden önceki durumu artık mevcut değildir.
connection.*Bağlanma, bağlantıyı kesme ve kimlik doğrulamanın durumu için GET /connected-accounts ve GET /connected-accounts/{connectedAccountId}/details. Google doğrulama olay çifti için herhangi bir konum okumasından googleVerificationStatus { status, message } değerini alın.Saatlik olarak; doğrulama devam ederken birkaç dakikada bir.failure_type (rejected ile transient arasındaki ayrım) ve reason dizesi. Bağlantının kopup yeniden kurulması görünmez: kopup yeniden kurulan bir bağlantı, okuma sonucunda bağlı olarak görünür.
interaction.*Konum başına GET /locations/{locationId}/reviews, konumlar genelinde GET /rollup_interactions, id değerine göre GET /reviewDetails.Yeni yorumlar için 15 dakikada bir, daha kapsamlı bir tarama için günlük olarak.Bir şeyin değişmiş olması. Belgelenen etkileşim alanları güncellenme zamanı içermez; bu nedenle düzenlenmiş bir yorum, daha önce kaydettiğiniz yorumla tamamen aynı görünür: sakladığınız alanları karşılaştırın.
local_post.*Site başına mevcut yayımlama durumu için GET /locations/{locationId}/posts, GET /locations/{locationId}/bulk-posts, GET /posts/{postId}.Gönderilerin yayımlanması devam ederken saatlik olarak.İletildiği hâliyle rejection_reason ve bir gönderi öğesinin sırasıyla geçtiği durumlar. Okumalar durum geçişlerini değil, mevcut durumu verir.
review_analytics.*Dönemin startDate ve endDate değerleriyle GET /locations/{locationId}/review-analytics-overview.Veri toplulaştırma süresi sona erdikten sonra günlük olarak, haftalık olay grubu için haftalık olarak.O an itibarıyla geçerli sayılar. Genel bakış okuma sırasında yeniden hesaplandığı için geç ulaşan veya silinen bir yorum, buradaki değerlerin anlık görüntüdeki değerlerden farklılaşmasına neden olur.

Teslimat sonuçları

Dışarıya hiçbir istek gönderilmeyenler de dahil olmak üzere her deneme bir durumla kaydedilir. Kullanılan durum dizeleri tam olarak aşağıdaki gibidir.

Dört sonuç ve bunları kaydeden durum dizeleri. 'Engellendi' ve 'istek sınırına takıldı', hiçbir HTTP isteği yapılmadığı anlamına gelir; bu nedenle bunları gerçek bir başarısızlıktan ayrı tutmak yararlıdır.
DurumSonuçAnlamıYapılması gereken
successTeslim edildiUç noktanız 2xx döndürdü.Hiçbir işlem gerekmez.
dize olarak bir HTTP kodu, e.g. "404", "500"Başarısız olduUç noktanız, 2xx aralığı dışındaki bu kodu döndürdü. Yönlendirmeler izlenmediği için 3xx da bu kapsama girer.Yolu, yönlendirme zincirini ve işleyicinizin hata oranını kontrol edin.
999Başarısız olduKullanılabilir bir durum kodu içermeyen bir yanıt alındı.Bunun nedeni genellikle uç noktanızın önündeki bir proxy veya yük dengeleyicidir.
timeoutBaşarısız oldu5 saniyelik süre sınırı içinde yanıt alınmadı.İşi istek işleme akışının dışına taşıyın ve alındı onayını daha erken verin.
network_errorBaşarısız olduAna bilgisayar adı çözümlenemedi veya ana bilgisayara erişilemedi.DNS'i ve ana bilgisayar adının genel internet üzerinden çözümlenebildiğini kontrol edin.
errorBaşarısız olduDeneme sırasında TLS el sıkışması hatası gibi yukarıdakilerden farklı bir hata oluştu.Sertifika zincirinizi ve sunucu günlüklerini kontrol edin.
blocked_urlEngellendiURL, bağlantı kurulurken yapılan güvenlik kontrolünden geçemedi: HTTPS kullanmıyordu, ana bilgisayar içermiyordu veya özel, geri döngü, yerel bağlantı ya da meta veri adresine çözümlendi.URL'yi genel internetten erişilebilen bir HTTPS ana bilgisayarını gösterecek şekilde ayarlayın. Bu kontrolün her teslimatta tekrarlandığını unutmayın; dolayısıyla bir DNS değişikliği, daha önce çalışan bir URL'nin engellenmesine neden olabilir.
endpoint_unverifiedEngellendiHesapta bir imzalama sırrı var, ancak uç nokta doğrulamadan geçmedi veya doğrulama sıfırlandı.Kontrol panelinden Uç noktayı doğrula işlemini yeniden çalıştırın.
rate_limitedİstek sınırına takıldıDakikalık veya günlük üst sınır aşıldı. Olay atıldı.İstek hacmini azaltın veya daha yüksek üst sınırı olan bir plana geçin. Planlar ve sınırlar bölümüne bakın.

Alıcı için kontrol listesi

  • Her istekte imzayı doğrulayın; eşleşme yoksa 401 döndürün ve hiçbir işlem yapmayın.
  • Hash değerini ham gövde baytları üzerinden hesaplayın; asla yeniden serileştirilmiş bir nesne üzerinden hesaplamayın.
  • 2xx yanıtını 5 saniyeden çok daha kısa sürede döndürün; işi kuyruğa alın.
  • Her işleyici yazma işleminde data içindeki kimlikleri anahtar olarak kullanın; böylece tekrarlar aynı sonucu üretir, ancak tekrarlanan bir kimliği asla yapılacak işlem olmadığı şeklinde yorumlamayın.
  • Geliş sırasından işlem sırası çıkarmayın ve timestamp değerine göre sıralama yapmayın.
  • location_id değerini alırken dizeye dönüştürün.
  • Tanımadığınız event değerlerini yok sayın ve yine de 200 döndürün.
  • Webhook URL'sini yönlendirme yapmayan nihai bir URL olarak sunun.
  • Verileri düzenli aralıklarla REST API ile karşılaştırıp eşitleyin; eksikleri giderecek bir yeniden deneme mekanizması yoktur.