وب هوک ها

وب هوک یک تماس HTTPS ایجاد شده توسط شریک است که مشخص می کند نماینده شما چگونه باید به پیام ها و رویدادها پاسخ دهد. هنگامی که وب هوک خود را پیکربندی کردید، می توانید شروع به دریافت پیام ها و رویدادها کنید.

وب هوک های شریک و وب هوک های عامل

می توانید وب هوک خود را در سطح شریک یا در سطح نماینده پیکربندی کنید.

  • وب هوک شریک شما برای هر عاملی که دارید اعمال می شود. اگر نمایندگان شما رفتار مشابهی دارند، یا اگر فقط یک نماینده دارید، از webhook شریک استفاده کنید.
  • وب‌قلاب‌های عامل برای نماینده‌های فردی اعمال می‌شود. اگر چندین عامل با رفتار متمایز کار می‌کنید، می‌توانید برای هر عامل یک وب هوک متفاوت تنظیم کنید .

اگر هم یک وب‌هوک شریک و هم وبک‌هوک عامل را پیکربندی کرده‌اید، وب‌هوک عامل بر عامل خاص خود اولویت دارد، در حالی که وب‌هوک شریک برای هر عاملی اعمال می‌شود که وب‌هوک خود را ندارد.

یک وبکهک عامل را پیکربندی کنید

شما پیام هایی را دریافت می کنید که برای نماینده خود در وب هوک شریک خود ارسال می شوند. اگر می‌خواهید پیام‌هایی برای یک نماینده خاص به وب‌هوک دیگری برسد، یک وب‌هوک نماینده تنظیم کنید.

  1. کنسول توسعه‌دهنده Business Communications را باز کنید و با حساب Google شریک RBM خود وارد شوید.
  2. روی نماینده خود کلیک کنید
  3. روی Integrations کلیک کنید.
  4. برای Webhook ، روی پیکربندی کلیک کنید.
  5. برای URL نقطه پایانی Webhook ، نشانی وب هوک خود را که با "https://" شروع می شود وارد کنید.
  6. به ارزش clientToken خود توجه کنید. برای تأیید اینکه پیام‌هایی که دریافت می‌کنید از Google ارسال می‌شوند به آن نیاز دارید.

  7. وب هوک خود را طوری پیکربندی کنید که درخواست 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);
});

  8. در Developer Console، روی تأیید کلیک کنید. هنگامی که RBM وب هوک شما را تأیید می کند، گفتگو بسته می شود.

پیام های دریافتی را تأیید کنید

از آنجایی که وب هوک ها می توانند از هر فرستنده ای پیام دریافت کنند، باید تأیید کنید که Google پیام های دریافتی را قبل از پردازش محتوای پیام ارسال کرده است.

برای تأیید اینکه Google پیامی را که دریافت کرده‌اید ارسال کرده است، این مراحل را دنبال کنید:

  1. هدر X-Goog-Signature پیام را استخراج کنید. این یک کپی هش شده و کدگذاری شده با base64 از بار بدنه پیام است.
  2. Base-64-بارگذاری RBM را در عنصر message.body درخواست رمزگشایی کنید.
  3. با استفاده از توکن کلاینت وب‌هوک خود (که هنگام راه‌اندازی وب‌هوک خود مشخص کرده‌اید) به‌عنوان یک کلید، یک SHA512 HMAC از بایت‌های بار پیام رمزگشایی شده base-64 ایجاد کنید و نتیجه را در base64 رمزگذاری کنید.
  4. هش X-Goog-Signature را با هشی که ایجاد کردید مقایسه کنید.
    • اگر هش ها مطابقت دارند، تأیید کرده اید که Google پیام را ارسال کرده است.

    • اگر هش ها مطابقت ندارند، روند هش خود را در یک پیام شناخته شده خوب بررسی کنید.

      اگر فرآیند هش شما به درستی کار می کند و پیامی دریافت می کنید که فکر می کنید به طور تقلبی برای شما ارسال شده است، با ما تماس بگیرید .

Node.js 

  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 از وب هوک یک شکست تحویل در نظر گرفته می شود.

توسعه‌دهندگان باید توجه داشته باشند که ارسال پیام‌ها با نرخ‌های بالا، اعلان‌های وب هوک را با نرخ‌های بالایی تولید می‌کند و باید کد خود را طوری طراحی کنند که مطمئن شوند می‌توانند اعلان‌ها را با نرخ مورد انتظار مصرف کنند. مهم است که توسعه‌دهندگان موقعیت‌هایی را در نظر بگیرند که ممکن است باعث پاسخ‌های شکست شوند - از جمله 500 پاسخ از محفظه وب، مهلت زمانی، یا خرابی‌های بالادستی. مواردی که باید در نظر بگیرید عبارتند از:

  • مطمئن شوید که حفاظت‌های DDoS شما به گونه‌ای پیکربندی شده‌اند که نرخ مورد انتظار اعلان‌های وب هوک را کنترل کند.
  • اطمینان حاصل کنید که منابعی مانند مخزن های اتصال پایگاه داده تمام نمی شوند و وقفه های زمانی یا 500 پاسخ ایجاد نمی کنند.

رفتار در هنگام تحویل شکست

RBM هنگامی که پاسخی غیر از 200 OK از یک تماس وب هوک دریافت می کند، از مکانیزم بازگشت و امتحان مجدد استفاده می کند. RBM زمان انتظار بین تلاش های مجدد را حداکثر تا 600 ثانیه افزایش می دهد. تلاش های مجدد به مدت 7 روز ادامه خواهد داشت و پس از آن پیام حذف خواهد شد.

مفاهیم وب هوک در سطح عامل

RBM پیام ها را برای یک شریک در یک صف قرار می دهد. در جایی که یک شریک از وبک‌هوک‌های سطح عامل استفاده می‌کند، مهم است که به خاطر داشته باشید که خرابی یک وبکهک بر تحویل به وبک‌هک‌های دیگر تأثیر می‌گذارد. وب هوک های متعلق به سایر عوامل در طول دوره بازگشت پیام ناموفق فراخوانی می شوند. با این حال، از آنجایی که پیام‌های ناموفق برای تلاش مجدد در صف قرار می‌گیرند، نرخ کلی تحویل کاهش می‌یابد و سایر عوامل تحت تأثیر قرار می‌گیرند.

مهم است که توسعه دهندگان این مدل و کد را بر اساس آن درک کنند - تا آنجا که ممکن است، پیام ها را بپذیرند و آنها را در صف پردازش قرار دهند تا فرصت بازگشت یک شکست را به حداقل برسانند.

مراحل بعدی

هنگامی که وب هوک خود را پیکربندی کردید، نماینده شما می تواند پیام هایی را از دستگاه های آزمایشی شما دریافت کند . برای تایید تنظیمات خود پیامی ارسال کنید .