مرجع الأحداث

جميع أحداث webhook في Listings API البالغ عددها 26، مجمّعة حسب المورد، مع الحقول الدقيقة ومثال على حمولة كل حدث.

26 حدثًا، مجمّعة حسب مورد REST الذي ترتبط به. يُرسَل كل حدث في هذه الصفحة إلى عنوان URL الوحيد المخصص لخطافات الويب لديك. لا يوجد اشتراك منفصل لكل حدث، لذا وجّه المعالجة حسب event وتجاهل ما لا تحتاج إليه.

تستخدم جميعها بنية البيانات القياسية باستثناء listing.submission، الموضّح أدناه. تُحذَف الحقول الاختيارية داخل data عندما تكون فارغة، بدلًا من إرسالها بقيمة null.

الفهرس

الحدث	المورد	يُطلَق عند
`listing.submission`	إدراجات الأنشطة التجارية	وصول إرسال بيانات استشهاد بنشاط تجاري إلى موقع دليل إلى نتيجة نهائية
`profile.created`	المواقع	إنشاء موقع
`profile.updated`	المواقع	تعديل موقع
`profile.deleted`	المواقع	أرشفة موقع
`connection.location_connected`	الحسابات المتصلة	ربط إدراج نشاط تجاري على Google أو Facebook
`connection.location_disconnected`	الحسابات المتصلة	إلغاء ربط إدراج نشاط تجاري
`connection.reauth_required`	الحسابات المتصلة	إبطال بيانات الاعتماد
`connection.listing_inaccessible`	الحسابات المتصلة	فقدان صلاحية الوصول إلى إدراج نشاط تجاري
`connection.google_verification_verified`	الحسابات المتصلة	نجاح التحقق لدى Google
`connection.google_verification_failed`	الحسابات المتصلة	فشل التحقق لدى Google
`interaction.review`	التقييمات	ورود تقييم أو تغييره
`interaction.response`	التقييمات	نشر رد أو تغييره
`local_post.created`	المنشورات	إنشاء منشور
`local_post.published`	المنشورات	نشر منشور على Google
`local_post.rejected`	المنشورات	رفض Google لمنشور
`local_post.deleted`	المنشورات	حذف منشور
`social_post.created`	Social	إنشاء منشور للتواصل الاجتماعي
`social_post.published`	Social	نشر منشور للتواصل الاجتماعي على كل قناة مستهدفة
`social_post.failed`	Social	فشل النشر على قناة واحدة على الأقل
`social_post.rejected`	Social	رفض المنشور ضمن سير عمل الموافقة
`social_post.deleted`	Social	أرشفة منشور للتواصل الاجتماعي
`social_connection.connected`	Social	ربط قناة للعلامة التجارية أو إعادة ربطها
`social_connection.disconnected`	Social	إزالة قناة للعلامة التجارية عمدًا
`social_connection.archived`	Social	فقدان قناة للعلامة التجارية دون قصد
`review_analytics.daily_snapshot`	التحليلات	تشغيل التجميع اليومي للتقييمات
`review_analytics.weekly_snapshot`	التحليلات	تشغيل التجميع الأسبوعي للتقييمات

إدراجات الأنشطة التجارية

يرتبط بنقاط نهاية إدراجات الأنشطة التجارية، وخصوصًا GET /locations/{locationId}/listings/premium، التي تُرجع syncStatus وlistingUrl لكل استشهاد، وهما القيمتان اللتان يُعلن عنهما هذا الحدث.

listing.submission

شرط الإطلاق: وصول إرسال بيانات استشهاد بنشاط تجاري لموقع واحد على موقع دليل واحد إلى حالة نهائية.

المستوى الأعلى:

الحقل	النوع	الوصف
`event`	string	دائمًا `listing.submission`.
`data`	object	انظر أدناه.
`status`	string	`success` أو `incomplete` أو `canceled`.
`live_link`	string	عنوان URL لإدراج النشاط التجاري المنشور. لا يظهر إلا في حالة `success`، وفقط عندما يكون العنوان معروفًا.
`error_message`	string	سبب تعذّر إكمال الإرسال. لا يظهر إلا في حالة `incomplete`.

داخل data:

الحقل	النوع	الوصف
`business_id`	integer	المعرّف الرقمي للموقع.
`v4_business_id`	string	`Location:<id>` بترميز base64، وهو صيغة المعرّف العام.
`location_id`	string	المعرّف العام نفسه بترميز base64، وليس سلسلة نصية رقمية.
`site.id`	integer	معرّف موقع الدليل.
`site.name`	string	اسم موقع الدليل، e.g. `Yelp`.
`site.url`	string	عنوان URL للصفحة الرئيسية لموقع الدليل.

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"}

المواقع

دورة حياة الموقع، مع تطابق بنسبة 1:1 مع createLocation وupdateLocation وarchiveLocations. النطاق خاص بالموقع: تكون location_id دائمًا سلسلة نصية رقمية.

profile.created

شرط الإطلاق: إنشاء موقع جديد.

حقل `data`	النوع	الوصف
`source`	string	الجهة التي أنشأته: `user` أو `api` أو `bulk_edit`.

JSON

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

profile.updated

شرط الإطلاق: تعديل تفاصيل موقع موجود.

يُحدّ التسليم إلى مرة واحدة لكل موقع كل 60 ثانية، عند بداية الفترة. تُدمَج التعديلات الواقعة خلال هذه الفترة، ولا يُؤجَّل تسليمها. ولا تُسلَّم مطلقًا. اعتبر changed_fields مؤشرًا إلى التعديل الذي بدأت به الفترة، وليس بيانًا كاملًا بالفروق.

يصل الحدث في بداية الفترة، لذا فإن إعادة قراءة الموقع عند وصوله لا تُظهر إلا ذلك التعديل الأول. جدوِل قراءة ثانية بعد انتهاء الفترة، أي بعد 60 ثانية على الأقل، وطابق بيانات المواقع دوريًا أيضًا، لأن لهذا الحدث محاولة تسليم واحدة دون إعادة محاولة. انظر تدارك حدث فائت.

حقل `data`	النوع	الوصف
`source`	string	`user` أو `api` أو `bulk_edit`.
`changed_fields`	array of string	أسماء حقول الموقع التي تغيّرت، e.g. `name`، `phone`، `address1`. يُحذَف الحقل عندما يكون فارغًا.

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

شرط الإطلاق: أرشفة موقع. هذا حذف منطقي. لا يوجد حذف نهائي، ويمكن إلغاء الأرشفة باستخدام cancelArchiveLocations، الذي لا يُطلِق حدثًا.

حقل `data`	النوع	الوصف
`source`	string	`user` أو `api` أو `bulk_edit`.

JSON

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

الحسابات المتصلة

دورة حياة اتصالات Google وFacebook وحالتها، إلى جانب نقاط نهاية الحسابات المتصلة. يقتصر نطاقها على الموقع. تكون قيمة platform دائمًا google أو facebook؛ ولا يصدر مقدمو الخدمات الآخرون هذه الأحداث.

يوجد connected_account_id دائمًا كمفتاح، لكن قيمته تكون null في حدثَي التحقق الخاصين بـ Google.

connection.location_connected

المُشغِّل: ربط إدراج نشاط تجاري على Google أو Facebook بموقع.

حقل `data`	النوع	الوصف
`platform`	string	`google` أو `facebook`.
`connected_account_id`	string	الحساب المتصل الذي جرى ربطه.

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

المُشغِّل: إلغاء ربط إدراج نشاط تجاري على Google أو Facebook بموقع.

حقل `data`	النوع	الوصف
`platform`	string	`google` أو `facebook`.
`connected_account_id`	string	الحساب المتصل الذي أُلغي ربطه.

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

المُشغِّل: إبطال بيانات الاعتماد للحساب المتصل. لن تجري مزامنة أي شيء عبر هذا الاتصال حتى يعيد أحدهم تفويضه.

حقل `data`	النوع	الوصف
`platform`	string	`google` أو `facebook`.
`connected_account_id`	string	الحساب المتصل الذي يحتاج إلى إعادة التفويض.
`reason`	string	وصف مقروء للمستخدم. يُحذف عندما لا يوفر المصدر وصفًا.

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

المُشغِّل: لم يعد الحساب المتصل قادرًا على الوصول إلى إدراج النشاط التجاري الخاص بالموقع. يختلف هذا عن reauth_required: فقد تظل بيانات الاعتماد صالحة تمامًا، لكن صلاحية الوصول إلى إدراج النشاط التجاري المحدد قد أُزيلت.

حقل `data`	النوع	الوصف
`platform`	string	`google` أو `facebook`.
`connected_account_id`	string	الحساب المتصل الذي فقد صلاحية الوصول.
`reason`	string	وصف مقروء للمستخدم. يُحذف عندما لا يوفر المصدر وصفًا.

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

المُشغِّل: اجتياز ملف Google Business Profile الخاص بموقع عملية التحقق.

حقل `data`	النوع	الوصف
`platform`	string	دائمًا `google`.
`connected_account_id`	null	دائمًا `null` في أحداث التحقق.

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

المُشغِّل: وصول عملية تحقق من ملف Google Business Profile إلى فشل نهائي. لا يبدأ أي استدعاء REST عملية تحقق؛ ويمكن قراءة الحالة نفسها كما هو موضح أعلاه.

لا تُصدر حدثًا إلا الحالات النهائية: تُطلِق VERIFIED الحدث _verified، وتُطلِق SUSPENDED أو DUPLICATE (failure_type rejected) وERROR_WHILE_FETCHING (transient) هذا الحدث. لا تُنتج الحالات التي تشير إلى أن العملية قيد التنفيذ (PENDING_VERIFICATION، UNDER_REVIEW، NOT_VERIFIED، NOT_CONNECTED) أي حدث على الإطلاق، لذا فإن غياب الحدث لا يدل على شيء. استعلم دوريًا عن googleVerificationStatus عند قراءة بيانات موقع ما دامت عملية التحقق قيد التنفيذ.

حقل `data`	النوع	الوصف
`platform`	string	دائمًا `google`.
`connected_account_id`	null	دائمًا `null` في أحداث التحقق.
`failure_type`	string	`rejected` لملف معلّق أو مكرر؛ و`transient` عند تعذّر قراءة البيانات من Google. لا تستحق إعادة المحاولة إلا في حالة `transient`.
`reason`	string	وصف مقروء للمستخدم. يُحذف عندما لا يوفر المصدر وصفًا.

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."  }}

التقييمات

التقييمات والردود، إلى جانب نقاط نهاية التقييمات، بما فيها الرد وتعديل الرد وأرشفة الرد.

تُستبعد التقييمات ضمن الفئة Social ولا تُسلَّم أبدًا.

interaction.review

المُشغِّل: استيعاب تقييم أو تغييره.

حقل `data.interaction`	النوع	الوصف
`id`	string	معرّف UUID للتفاعل. يحدد التقييم، وليس هذا التغيير: يصل المعرّف نفسه مجددًا كلما تغيّر التقييم. استخدمه مفتاحًا للصف؛ ولا تستخدمه أبدًا لمنع تسليم لاحق. راجع التكرارات والترتيب.
`type`	string	`Review`.
`content`	string	نص التقييم. قد تكون قيمته `null`.
`rating`	number	التقييم بالنجوم. قد تكون قيمته `null` للمصادر التي لا توفر هذا التقييم.
`title`	string	عنوان التقييم، إن كان المصدر يوفره.
`author_name`	string	اسم العرض لكاتب التقييم.
`author_avatar`	string	عنوان URL للصورة الشخصية لكاتب التقييم.
`date`	string	تاريخ نشر التقييم في المصدر بتنسيق ISO-8601.
`source`	string	المصدر الذي وردت منه، e.g. `google.com`، `facebook.com`.
`permalink`	string	رابط التقييم في المصدر.
`category`	string	فئة التفاعل. تُستبعد `Social` قبل التسليم.
`interaction_status`	string	حالة التفاعل في سير العمل.
`parent_id`	string	دائمًا `null` للتقييم.
`interaction_request_id`	string	الطلب الذي ينتمي إليه هذا التفاعل. قد تكون قيمته `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

المُشغِّل: نشر رد على تقييم أو تعديله أو أرشفته. له البنية نفسها التي لـ interaction.review، مع اختلافين: تكون قيمة type هي Response، ويشير parent_id إلى التقييم الذي يُرد عليه.

حقل `data.interaction`	النوع	الوصف
`type`	string	`Response`.
`parent_id`	string	معرّف UUID للتقييم الذي يجيب عنه هذا الرد.
`content`	string	نص الرد.
`rating`	number	دائمًا `null` للرد.

توجد جميع الحقول الأخرى المدرجة تحت interaction.review بالمعنى نفسه.

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"    }  }}

المنشورات

المنشورات المحلية على Google Business Profile، إلى جانب نقاط نهاية المنشورات. نطاقها محدد بموقع، وlocation_id سلسلة نصية رقمية.

تشترك الأحداث الأربعة في بنية واحدة لـ data؛ وتختلف الحقول الاختيارية. تُحذف جميع الحقول الاختيارية عندما تكون فارغة.

حقل `data`	النوع	الوصف
`post_id`	integer	المنشور الذي ينتمي إليه هذا العنصر، وهو المعرّف الذي تعيده نقاط نهاية الإنشاء.
`post_item_id`	integer	العنصر الخاص بكل موقع. ينتج عن نشر منشور في 20 موقعًا 20 عنصرًا، وتكون الأحداث لكل عنصر.
`post_type`	string	`STANDARD` أو `EVENT` أو `OFFER`.
`post_external_id`	string	اسم المورد الذي تخصصه Google للمنشور. لا يكون موجودًا حتى تقبله Google.
`published_url`	string	عنوان URL يمكن فتحه في المتصفح. يكون غير موجود عادةً: لا تعيده Google بشكل موثوق؛ استخدم `post_external_id` لربط السجلات.
`rejection_reason`	string	في `local_post.rejected` فقط.

local_post.created

سبب الإطلاق: إنشاء عنصر منشور وإضافته إلى قائمة الانتظار لإرساله إلى Google. لم يُنشر بعد.

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

سبب الإطلاق: قبول Google للمنشور وإتاحته للجمهور.

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

سبب الإطلاق: رفض Google للمنشور، أو فشل إرساله.

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

سبب الإطلاق: حذف عنصر المنشور.

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"  }}

النشر على وسائل التواصل الاجتماعي على مستوى العلامة التجارية ودورة حياة الاتصالات، إلى جانب نقاط نهاية Social. تسعة أحداث: خمسة للمنشورات وأربعة للاتصالات.

يوجد account_id وtimestamp كالمعتاد. المعرّفات داخل data هي معرّفات UUID البسيطة نفسها التي تستخدمها واجهة REST API، وتُرسل كسلاسل نصية.

social_post.created

سبب الإطلاق: إنشاء منشور على وسائل التواصل الاجتماعي. عند الإنشاء فقط — لا يؤدي تعديل منشور موجود إلى إصدار الحدث مجددًا.

حقل `data`	النوع	الوصف
`post_id`	string	معرّف UUID للمنشور، وهو `socialPostId` نفسه الذي تعيده نقطة نهاية الإنشاء.
`social_profile_id`	string	العلامة التجارية التي ينتمي إليها المنشور. تكون القيمة `null` إذا لم تكن للمنشور علامة تجارية.
`status`	string	حالة المنشور عند إنشائه.
`created_by`	integer	المستخدم الذي أنشأه.
`platform_ids`	array of integer	المعرّفات الداخلية للمنصات التي يستهدفها المنشور.

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

سبب الإطلاق: نشر المنشور بالكامل. يُصدر هذا الحدث فقط عند النجاح الكامل: نُشر المنشور على قناة واحدة على الأقل، ولم يحدث أي خطأ في أي قناة. لا يؤدي النشر الجزئي إلى إصداره — بل يُصدر في هذه الحالة social_post.failed.

حقل `data`	النوع	الوصف
`post_id`	string	معرّف UUID للمنشور.
`social_profile_id`	string	العلامة التجارية التي ينتمي إليها المنشور.
`status`	string	حالة المنشور.
`published_on`	string	وقت إتاحة المنشور للجمهور بتنسيق ISO-8601. تكون القيمة `null` إذا لم يُسجّل.
`items`	array of object	سجل واحد لكل قناة؛ الحقول أدناه.
`items[].platform`	string	اسم المنصة، e.g. `instagram`.
`items[].social_platform_id`	integer	المعرّف الداخلي للمنصة.
`items[].connected_account_id`	string	معرّف UUID للاتصال الذي نُشر المنشور من خلاله.
`items[].published_url`	string	عنوان URL المتاح للجمهور للعنصر المنشور.
`items[].vendor_post_id`	string	المعرّف الذي تخصصه المنصة للعنصر المنشور.
`items[].status`	string	حالة تلك القناة.

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

سبب الإطلاق: فشل النشر. هذا فشل في التسليم، وهو مختلف عن الرفض التحريري. يُطلق عند آخر محاولة لإعادة المحاولة، لذا لا يُصدر ما دامت هناك محاولات متبقية للمنشور.

يحتوي items على القنوات التي حدثت فيها أخطاء فقط، لذا يصل هنا المنشور الذي نُشر على منصتين وفشل على ثالثة بعنصر واحد.

حقل `data`	النوع	الوصف
`post_id`	string	معرّف UUID للمنشور.
`social_profile_id`	string	العلامة التجارية التي ينتمي إليها المنشور.
`status`	string	حالة المنشور.
`items`	array of object	سجل واحد لكل قناة فشل النشر فيها؛ الحقول أدناه.
`items[].platform`	string	اسم المنصة.
`items[].social_platform_id`	integer	المعرّف الداخلي للمنصة.
`items[].status`	string	حالة تلك القناة.
`items[].reason`	string	سبب موجز، يُقتطع إلى 300 حرف. قد تكون القيمة `null`.
`items[].vendor_error`	string	رسالة محدودة الطول وآمنة للعرض على المستخدم، مشتقة من خطأ المنصة. لا تتضمن أبدًا حمولة المنصة الخام. قد تكون القيمة `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

سبب الإطلاق: رفض المنشور ضمن سير عمل للموافقة. هذا رفض تحريري، وليس فشلًا في التسليم: لم يصل المنشور إلى أي منصة.

حقل `data`	النوع	الوصف
`post_id`	string	معرّف UUID للمنشور.
`social_profile_id`	string	العلامة التجارية التي ينتمي إليها المنشور.
`status`	string	حالة المنشور.
`rejection_reason`	string	تعليق المراجع. تكون القيمة `null` عندما لا يترك تعليقًا.

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

سبب الإطلاق: أرشفة المنشور، سواء عبر POST /social/posts/cancel أو من خلال عملية الأرشفة الدورية المجدولة. لا يُطلق إلا عند حدوث انتقال فعلي في الحالة، لذا لا تؤدي إعادة أرشفة منشور مؤرشف بالفعل إلى إصدار أي حدث.

حقل `data`	النوع	الوصف
`post_id`	string	معرّف UUID للمنشور.
`social_profile_id`	string	العلامة التجارية التي ينتمي إليها المنشور.
`status`	string	حالة المنشور.
`archived_at`	string	وقت أرشفة المنشور بتنسيق ISO-8601. تكون القيمة `null` إذا لم يُسجّل.

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

سبب الإطلاق: تنشيط قناة للعلامة التجارية، سواء عند اتصالها لأول مرة أو عند إعادة اتصال قناة كانت مؤرشفة. يميّز is_reconnect بين الحالتين.

حقل `data`	النوع	الوصف
`social_profile_id`	string	العلامة التجارية المرتبطة بها القناة.
`connected_account_id`	string	معرّف UUID للاتصال، وهو `id` الذي تعيده قائمة الاتصالات.
`platform`	string	اسم المنصة، e.g. `instagram`.
`display_name`	string	اسم العرض للقناة. قد تكون القيمة `null`.
`is_reconnect`	boolean	`false` عند الاتصال لأول مرة، و`true` عند عودة قناة كانت مؤرشفة.
`listing_connected_account_id`	string	يوجد فقط عندما تكون القناة مرتبطة أيضًا بحساب متصل في Listings. يُحذف في غير ذلك.

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

سبب الإطلاق: إزالة القناة عمدًا باستخدام استدعاء قطع الاتصال. لا يُصدر إلا عندما تُؤرشف القناة بالفعل، لذا لا تؤدي محاولة قطع اتصال فاشلة إلى إصدار حدث غير صحيح.

حقل `data`	النوع	الوصف
`social_profile_id`	string	العلامة التجارية التي كانت القناة مرتبطة بها.
`connected_account_id`	string	معرّف UUID للاتصال.
`platform`	string	اسم المنصة.
`display_name`	string	اسم العرض للقناة. قد تكون القيمة `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

سبب الإطلاق: فقدان الاتصال بالقناة دون قصد — أبطلت المنصة رمز الوصول، أو اكتشفت عملية مطابقة الحالة أنه لم يعد من الممكن الوصول إلى القناة. لم يطلب أحد ذلك، وهذا ما يميّزه عن disconnected.

حقل `data`	النوع	الوصف
`social_profile_id`	string	العلامة التجارية التي كانت القناة مرتبطة بها.
`connected_account_id`	string	معرّف UUID للاتصال.
`platform`	string	اسم المنصة.
`display_name`	string	اسم العرض للقناة. قد تكون القيمة `null`.
`reason`	string	سبب فقدان الاتصال بها. قد تكون القيمة `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."  }}

تحليلات التقييمات

ملخصات مجدولة للتقييمات، بواقع حدث واحد لكل موقع في كل فترة.

يشترك الحدثان في بنية data واحدة:

حقل `data`	النوع	الوصف
`period`	string	بداية الفترة، `YYYY-MM-DD`.
`granularity`	string	`daily` أو `weekly`.
`total_reviews`	integer	إجمالي عدد التقييمات للموقع منذ البداية.
`new_reviews_in_period`	integer	التقييمات المستلمة خلال هذه الفترة.
`average_rating`	number	متوسط التقييم لهذه الفترة، بدقة 4 منازل عشرية. تكون القيمة `0.0` إذا لم تكن هناك تقييمات.
`previous_average_rating`	number	متوسط التقييم للفترة السابقة. تكون القيمة `0.0` إذا لم تتوفر بيانات سابقة.

لا يصدر الموقع الذي لم يشهد نشاطًا خلال الفترة أي حدث، لكن النتيجة نفسها تحدث عندما لا تصل لقطة الموقع. غياب اللقطة لا يحدد السبب، وفي هذه الفئة يكون التفسير الذي لا يشير إلى مشكلة هو الأقل احتمالًا. فقد يعني ذلك: عدم وجود نشاط؛ أو فشل التسليم أو انتهاء مهلته (توجد محاولة واحدة دون إعادة محاولة)؛ أو منع التسليم لأن الحساب لا يملك صلاحية استخدام webhooks، أو لم يُضبط له عنوان URL، أو لم يتم التحقق منه أو كان محظورًا؛ أو، وهو الأرجح هنا، إسقاط الحد الأقصى لكل دقيقة جزءًا من الدفعة بوصفه rate_limited.

لا تسجّل قيمة صفر مطلقًا استنادًا إلى غياب اللقطة. طابق البيانات مع GET /locations/{locationId}/review-analytics-overview للفترة نفسها، وإذا فشلت عملية القراءة هذه أيضًا، فأبلغ بأن بيانات الفترة غير متاحة بدلًا من تسجيلها بقيمة صفر.

review_analytics.daily_snapshot

المُشغِّل: مهمة إعداد الملخص اليومي، مرة واحدة لكل موقع في اليوم.

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

المُشغِّل: مهمة إعداد الملخص الأسبوعي، مرة واحدة لكل موقع في الأسبوع. يشير period إلى اليوم الأول من الأسبوع الذي يجري تلخيصه.

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  }}

أحداث قد تتلقاها ولكن ينبغي ألا تعتمد عليها في التطوير

تُصدر المنصة فئات أخرى من الأحداث: حملات التقييمات، والترتيب، وترويج منشورات التواصل الاجتماعي، وتغييرات حالة حسابات الإعلانات على منصات التواصل الاجتماعي، وأفكار المنشورات بالذكاء الاصطناعي، وملكية Google Business Profile. لا توجد لها نقطة نهاية REST منشورة في Listings API، وهي غير موثّقة هنا، ولا تشمل بُناها أي ضمانات للتوافق. نظرًا إلى وجود عنوان URL واحد وعدم وجود اشتراك منفصل لكل حدث، ينبغي أن يتجاهل المعالج لديك أي event لا يتعرف عليه، وأن يعيد 200 رغم ذلك.