وبهوک یک URL مشخصشده توسط شریک است که پلتفرم RBM پیامها و رویدادها را در آن ارسال میکند. این URL به عنوان یک نقطه پایانی عمل میکند که درخواستهای HTTPS POST حاوی دادههای مربوط به رویدادها را دریافت میکند. این بدان معناست که دادهها به طور ایمن از طریق HTTPS به برنامه شما ارسال میشوند.
یک آدرس اینترنتی وبهوک ممکن است چیزی شبیه به این باشد: https://[your company name].com/api/rbm-events . پس از پیکربندی وبهوک، میتوانید پیامها و رویدادها را دریافت کنید.
وبهوکهای شریک و وبهوکهای نماینده
شما میتوانید وبهوک خود را در سطح همکار یا در سطح نماینده پیکربندی کنید.
- وبهوک شریک شما برای هر ایجنتی که نگهداری میکنید اعمال میشود. اگر ایجنتهای شما رفتار مشابهی دارند، یا اگر فقط یک ایجنت دارید، از وبهوک شریک استفاده کنید.
- وبهوکهای عامل برای عاملهای منفرد اعمال میشوند. اگر چندین عامل با رفتار متمایز را مدیریت میکنید، میتوانید برای هر عامل یک وبهوک متفاوت تنظیم کنید .
اگر هم وبهوک همکار و هم وبهوک عامل را پیکربندی کرده باشید، وبهوک عامل بر عامل خاص خود اولویت دارد، در حالی که وبهوک شریک برای هر عاملی که وبهوک مخصوص به خود را ندارد اعمال میشود.
پیکربندی وبهوک عامل
شما پیامهای ارسالی به نماینده خود را در وبهوک همکارتان دریافت میکنید. اگر میخواهید پیامهای یک نماینده خاص به وبهوک دیگری ارسال شود، یک وبهوک برای نماینده تنظیم کنید.
- کنسول توسعهدهندگان ارتباطات تجاری را باز کنید و با حساب گوگل شریک RBM خود وارد شوید.
- روی نماینده خود کلیک کنید.
- روی ادغامها کلیک کنید.
- برای وبهوک ، روی پیکربندی کلیک کنید.
- برای آدرس اینترنتی نقطه پایانی وبهوک ، آدرس اینترنتی وبهوک خود را که با "https://" شروع میشود، وارد کنید.
- مقدار
clientTokenخود را یادداشت کنید. برای تأیید اینکه پیامهای دریافتی از Google میآیند، به آن نیاز دارید. وبهوک خود را طوری پیکربندی کنید که یک درخواست
POSTبا پارامترclientTokenمشخص شده را بپذیرد و یک پاسخ200 OKبا مقدار متن ساده پارامترsecretبه عنوان بدنه پاسخ ارسال کند.برای مثال، اگر وبهوک شما یک درخواست
POSTبا محتوای بدنه زیر دریافت کند{ "clientToken":"SJENCPGJESMGUFPY", "secret":"1234567890" }سپس وبهوک شما باید مقدار
clientTokenرا تأیید کند و اگرclientTokenصحیح باشد، یک پاسخ200 OKبا1234567890به عنوان بدنه پاسخ برگرداند:// clientToken from Configure const myClientToken = "SJENCPGJESMGUFPY"; // Example endpoint app.post("/rbm-webhook", (req, res) => { const msg = req.body; if (msg.clientToken === myClientToken) { res.status(200).send(msg.secret); return; } res.send(400); });در کنسول توسعهدهندگان، روی تأیید کلیک کنید. وقتی RBM وبهوک شما را تأیید کرد، پنجره بسته میشود.
تأیید پیامهای دریافتی
از آنجا که وبهوکها میتوانند از هر فرستندهای پیام دریافت کنند، باید قبل از پردازش محتوای پیام، تأیید کنید که گوگل پیامهای دریافتی را ارسال کرده است.
برای تأیید اینکه گوگل پیامی را که دریافت کردهاید ارسال کرده است، این مراحل را دنبال کنید:
- هدر
X-Goog-Signatureپیام را استخراج کنید. این یک کپی هش شده و کدگذاری شده با base64 از محتوای بدنه پیام است. - کد RBM موجود در عنصر
message.bodyدرخواست را با استفاده از Base-64 رمزگشایی کنید. - با استفاده از توکن کلاینت وبهوک خود (که هنگام تنظیم وبهوک مشخص کردهاید) به عنوان کلید، یک SHA512 HMAC از بایتهای پیام رمزگشاییشدهی base-64 ایجاد کنید و نتیجه را base64-encode کنید.
- هش
X-Goog-Signatureرا با هشی که ایجاد کردهاید مقایسه کنید.- اگر هشها مطابقت داشته باشند، شما تأیید کردهاید که گوگل پیام را ارسال کرده است.
اگر هشها مطابقت ندارند، فرآیند هش کردن خود را روی یک پیام شناختهشده و بدون مشکل بررسی کنید.
اگر فرآیند هش کردن شما به درستی کار میکند و پیامی دریافت میکنید که معتقدید به صورت جعلی برای شما ارسال شده است، با ما تماس بگیرید .
نود جی اس
if ((requestBody.hasOwnProperty('message')) && (requestBody.message.hasOwnProperty('data'))) { // Validate the received hash to ensure the message came from Google RBM let userEventString = Buffer.from(requestBody.message.data, 'base64'); let hmac = crypto.createHmac('sha512', CLIENT_TOKEN); let data = hmac.update(userEventString); let genHash = data.digest('base64'); let headerHash = req.header('X-Goog-Signature'); if (headerHash === genHash) { let userEvent = JSON.parse(userEventString); console.log('userEventString: ' + userEventString); handleMessage(userEvent); } else { console.log('hash mismatch - ignoring message'); } } res.sendStatus(200);
مدیریت پیام
برگرداندن هر چیزی غیر از 200 OK از یک وبهوک، به عنوان شکست در تحویل (delivery failure) در نظر گرفته میشود.
توسعهدهندگان باید توجه داشته باشند که ارسال پیامها با نرخ بالا، اعلانهای وبهوک را با نرخ بالا ایجاد میکند و باید کد خود را طوری طراحی کنند که اعلانها را با نرخ مورد انتظار مدیریت کند. برای توسعهدهندگان مهم است که موقعیتهایی را که ممکن است باعث پاسخهای ناموفق شوند - از جمله 500 پاسخ از کانتینر وب، وقفههای زمانی یا خرابیهای بالادستی - در نظر بگیرند. مواردی که باید در نظر گرفته شوند عبارتند از:
- تأیید کنید که محافظتهای DDoS شما برای مدیریت نرخ مورد انتظار اعلانهای وبهوک پیکربندی شدهاند.
- تأیید کنید که منابعی مانند مجموعههای اتصال پایگاه داده، تمام نشوند و باعث وقفه یا پاسخهای
500نشوند.
توسعهدهندگان باید سیستمهای خود را طوری طراحی کنند که پردازش رویدادهای RBM به صورت غیرهمزمان انجام شود و مانع از بازگشت 200 OK توسط وبهوک نشود.
مهم است که رویداد RBM را درون خود وبهوک پردازش نکنید . هرگونه خطا یا تأخیر در طول پردازش ممکن است بر کد برگشتی وبهوک تأثیر بگذارد:
رفتار در هنگام عدم تحویل
RBM وقتی پاسخی غیر از 200 OK از یک فراخوانی وبهوک دریافت میکند، از مکانیزم backoff و retry استفاده میکند. RBM زمان انتظار بین تلاشهای مجدد را تا حداکثر 600 ثانیه افزایش میدهد. تلاشهای مجدد به مدت 7 روز ادامه خواهد داشت و پس از آن پیام حذف میشود.
پیامدهای وبهوکهای سطح عامل
RBM پیامهای مربوط به یک شریک را در یک صف قرار میدهد. در جایی که یک شریک از وبهوکهای سطح عامل استفاده میکند، باید در نظر داشت که خرابی یک وبهوک بر تحویل به وبهوکهای دیگر تأثیر میگذارد. وبهوکهای متعلق به سایر عاملها در طول دورهی غیرفعال شدن یک پیام ناموفق فراخوانی میشوند. با این حال، از آنجایی که پیامهای ناموفق برای تلاش مجدد در صف قرار میگیرند، نرخ کلی تحویل کاهش مییابد و سایر عاملها تحت تأثیر قرار میگیرند.
مهم است که توسعهدهندگان این مدل را درک کنند و بر اساس آن کدنویسی کنند - تا حد امکان، پیامها را بپذیرند و آنها را برای پردازش در صف قرار دهند تا احتمال بازگشت خطا به حداقل برسد.
مراحل بعدی
پس از پیکربندی وبهوک، عامل شما میتواند پیامهایی را از دستگاههای آزمایشی شما دریافت کند. برای تأیید تنظیمات خود، پیامی ارسال کنید .