نظرة عامة على Webhooks

كيف ترسل Listings API أحداث الحساب إلى خادمك، وما الأحداث المتاحة، وما شروط التحقق الخمسة التي يجب أن يستوفيها كل إرسال.

الاستعلام الدوري من API لمعرفة ما إذا كان شيء قد تغيّر مكلف، ويكشف التغيير دائمًا بعد تأخير بسيط. تعكس webhooks هذا الأسلوب: عندما يحدث شيء في حسابك (يصل تقييم، أو يُعدّل موقع، أو يُنشر منشور على Google Business)، ترسل Listings API طلب HTTP POST يتضمن محتوى بصيغة JSON إلى عنوان URL تتحكم فيه، خلال ثوانٍ.

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

مسار معالجة التسليم

ما يمكنك استقباله

18 حدثًا موزعة على 6 مجموعات. يقابل كل حدث موردًا تديره بالفعل عبر REST API، لذا يخبرك webhook متى حدث التغيير، وتخبرك نقطة النهاية ما الذي تغيّر.

تتوفر جداول الحقول الكاملة وأمثلة على حمولات البيانات في مرجع الأحداث.

خارج النطاق

تُصدر المنصة مجموعات أحداث أخرى لا توثّقها Listings API ولا تدعمها، لعدم وجود نقطة نهاية REST منشورة لها هنا. وهي مدرجة حتى لا يبدو أن أي شيء قد أُغفل سهوًا:

• حملات التقييمات: campaign.*
• الترتيب في نتائج البحث: rankings.*
• منشورات Social وترويجها: social_post.*
• اتصالات Social: social_connection.*
• أفكار منشورات بالذكاء الاصطناعي: idea.*، idea_series.*، idea_pipeline.*، idea_image.*
• ملكية Google Business Profile: gbp_ownership.*

ملاحظتان يجب قراءتهما قبل البدء بالتطوير

شروط التسليم

يتوقف التسليم على خمسة شروط، تُفحص بهذا الترتيب. يتوقف التسليم عند أول شرط غير مستوفى؛ ولا تُفحص الشروط اللاحقة مطلقًا.

الخطط والحدود

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

تُحتسَب عمليات التسليم أيضًا ضمن حد أقصى لكل دقيقة وحد أقصى لكل يوم، ويُحدَّد كلاهما وفق خطتك.

تطابق الحدود القصوى لإشعارات webhook حدود طلبات API في خطتك: حصة الأحداث التي نرسلها إليك تساوي حصة الطلبات التي ترسلها إلينا.

لا يبدأ تطبيق أي حد أقصى على حسابك إلا بعد مزامنة حدود خطتك مع مسار التسليم. وحتى يحدث ذلك، لا يوجد حد أقصى يُفحَص، لذا لا تُحتسَب أي عمليات تسليم ولا تُسقَط أي أحداث. لذلك قد يتلقى الحساب الجديد تمامًا عمليات تسليم دون احتسابها ضمن حصة قبل بدء تطبيق الحد الأقصى لخطته. لا تعتبر غياب rate_limited دليلًا على أنك لم تتجاوز الحد.

كيفية عمل احتساب الاستخدام:

• نافذتان زمنيتان ثابتتان ومستقلتان: واحدة لكل دقيقة، وأخرى لكل يوم. لا توجد نافذة زمنية لكل ساعة لإشعارات webhook. (نظام تحديد معدل الطلبات نظام مختلف ذو نوافذ زمنية مختلفة؛ ولا يشترك النظامان في حصة واحدة.)
• تتوافق النوافذ الزمنية مع حدود التقويم، وليست متحركة: يُصفَّر عدّاد الدقيقة عند بداية كل دقيقة، ويُصفَّر العدّاد اليومي عند بداية كل يوم بتوقيت UTC.
• يُسقَط الحدث عند تجاوز الحد. لا يُوضَع في قائمة انتظار، ولا يُؤجَّل، ولا تُعاد محاولة تسليمه: لا توجد قائمة انتظار لإعادة المحاولة في أي موضع من مسار الإرسال الصادر، ولا توجد جهة مستدعية لإرجاع 429 إليها. تُسجَّل المحاولة بحالة التسليم rate_limited حتى يكون الفقد ظاهرًا بدلًا من أن يحدث دون إشعار.
• يسمح نظام تحديد المعدل بالتسليم عند تعطّله. إذا تعذّر على نظام تحديد المعدل نفسه الرد، تُنفَّذ عملية التسليم بدلًا من إسقاط الحدث. لن تفقد أي حدث بسبب تعطل احتساب الاستخدام.

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

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

الإعداد

1. أنشئ نقطة نهاية HTTPS. يجب أن يكون اسمها قابلًا للتحويل إلى عنوان IP عبر الإنترنت، وأن تكون لها شهادة صالحة، وأن تقبل POST وترد بـ 2xx في أقل من 5 ثوانٍ. تُرفض العناوين الخاصة والداخلية (loopback وRFC-1918 وlink-local وعناوين IP لخدمات البيانات الوصفية السحابية).
2. احفظ عنوان URL الخاص بـ webhooks في صفحة Webhooks في لوحة التحكم. يُستخدم عنوان URL واحد لكل حساب، لجميع الأحداث.
3. أنشئ سرًا للتوقيع وخزّنه على خادمك. يُعرض مرة واحدة. من هذه اللحظة، تُوقَّع عمليات التسليم ويصبح التحقق مطلوبًا.
4. تحقّق من نقطة النهاية. ترسل المنصة تحديًا موقّعًا؛ وتجيب نقطة النهاية بقيمة HMAC للـ nonce بتمثيل سداسي عشري. عند النجاح، تصبح نقطة النهاية موثّقة وتبدأ عمليات التسليم. راجع التوقيعات والتحقق للاطلاع على المواصفات الدقيقة وكود قابل للتشغيل.
5. عالِج الأحداث. تحقّق من التوقيع، وأضف الحمولة إلى قائمة الانتظار، وأعِد 200. نفّذ المعالجة الفعلية خارج مسار معالجة الطلب. راجع سلوك التسليم للاطلاع على مهلة الانتظار وسياسة المحاولة الواحدة وما يمكن توقعه بشأن التكرار والترتيب.

الخطوات التالية

• التوقيعات والتحقق: ترويسة X-ListingsAPI-Signature، وقاعدة استخدام جسم الطلب الخام، والمصافحة.
• سلوك التسليم: الحمولة القياسية، ومهلة الانتظار البالغة 5 ثوانٍ، وسبب عدم إعادة المحاولة، وجميع حالات التسليم.
• مرجع الأحداث: جميع الأحداث الـ 18، حقلًا بحقل.