Работа с вебхуками и уведомлениями#

Получение входящих данных в GREEN-API реализовано через входящие уведомления. Есть 2 способа получать уведомления HTTP API и Webhook Endpoint.

Ниже приведены рекомендации по работе с вебхуками и уведомлениями:

1. Получение входящих уведомлений
2. Обработка входящих уведомлений
3. Безопасность при получении уведомлений
4. Логирование и обработка ошибок
5. Масштабирование и распределение нагрузки

1. Получение входящих уведомлений#

Работа через HTTP API#

При работе через методы HTTP API требуется вызывать последовательно 2 метода API:

1. Вызываем метод receiveNotification в зависимости от наличия сообщений, настроек метода и настроек инстанса в ответе Вы получете объект с номером и объектом уведомления.

   Если уведомлений в очереди нет, в ответе придет null.

2. После получения уведомления необходимо обработать входящее уведомление обработчиком и удалить уведомление методом deleteNotification передав номер этого уведомления.

   Если метод завершился статус кодом 500 и более требуется повторить запрос метода.

Работа через Webhook Endpoint#

При работе через методы Webhook Endpoint требуется настроить веб-сервер, способный принимать HTTP запросы.

Веб-сервер должен:

1. Принять входящий POST запрос (вебхук)

2. Обработать принятое уведомление

3. Вернуть ответ с кодом состояния 200 (после получения от сервера статус кода 200 уведомление будет удалено из очереди).

   Время ожидания ответа от Вашего веб-сервера составляет 180 секунд, если сервер не отдаст статус код 200, сервер GREEN-API сделает паузу в 60 секунд и повторит отправку текущего уведомления.

2. Обработка входящих уведомлений#

Все типы и форматы уведомлений указаны в документации.

Рекомендуется сделать обработку входящих уведомлений согластно инструкции ниже:

1. После получения уведомления сервисом обработчика, желательно проверить схему уведомления (JSONSchema).

   Не рекомендуется делать проверку схемы на дополнительные поля, так как API может расширятся добавляя новые функции и информацию.
   Если Вы получили уведомление в котором отсутствует поле или его формат не верный, требуется зафиксировать такое уведомление в системе логирования и проинформировать оперетора указав данное уведомление, это поможет зафиксировать и разобраться в ошибке в будущем.

2. Сервис обработчика должен найти обязательное поле typeWebhook и в зависимости от его типа обработать или сбросить уведомление.

3. После обработки уведомления обработчик должет отдать статус код 200.

   Так все не обрабатываемые вам уведомления будут удаляться из очереди и последующие уведомления будут приходить корректно.
   Если Вы не используете некоторые типы уведомлений, то рекомендуем делать сброс не нужных уведомлений, отдавая статус код 200, так Вы исключите ошибки обработчика и при выходе нового функционала у Вас не возникнет проблем в работе интеграции.

Пример простого веб-сервера от GREEN-API:

• Python с инструкцией по установке.

• Golang с инструкцией по установке.

• NodeJS с инструкцией по установке.

3. Безопасность при получении уведомлений#

При проектировании сервиса необходимо уделить внимание безопасности.

При работе с технологией HTTP API Ваш IP адрес закрыт и не доступен другим пользователем интернета, данная технология хороша работает в небольших системах с малым объемом данных.

При работе с технологией Webhook Endpoint Ваш IP адрес доступен другим пользователем, требуется исключить вредоностные воздействия на Вашу систему извне.

Рекомендации по безопасности при использовании технологии Webhook Endpoint:

1. Настройте сетевой экран (Firewall), разрешите доступ к серверу только с требуемых Вам IP адресов.

2. Ограничение доступа только с определённых IP адресов. Вы можете настроить Ваш веб-сервер таким образом, чтобы он принимал входящие запросы только с IP адресов GREEN-API.

3. Использовать токен авторизации при отправке уведомлений. Укажите токен авторизации в поле webhookUrlToken через личный кабинет или методом установки настроек setSettings.

from flask import Flask, request

from datetime import datetime
import json

app = Flask(**name**)

# Список IP-адресов GREEN-API

ALLOWED_IPS = [
   "51.250.84.44",
   "51.250.94.65",
   "51.250.89.177",
   "64.226.125.75",
   "158.160.49.84",
   "46.101.109.139",
   "51.250.95.149",
   "51.250.12.167",
   "209.38.202.24"]

# Функция для проверки разрешенных IP-адресов

def check_ip():
client_ip = request.remote_addr
if client_ip not in ALLOWED_IPS:
return False
return True

@app.before_request
def before_request():
if not check_ip():
return "Access Denied", 403

# Остальной код вашего приложения...

if **name** == "**main**":
app.run()

4. Логирование и обработка ошибок#

Рекомендуется настроить систему логирования:

1. Используете многоуровневую настраиваемую систему логирования. Логируйте проблемы схемы на уровне ERROR, новые типы уведомлений на уровне WARN, необрабатываемые типы сообщений на уровне DEBUG и работу системы на уровне INFO. Включая нужный уровень логирования, Вы сможете отлаживать работу системы и определять все проблемы, связанные с интеграцией.

2. Рекомендуется сообщать оператору о неизвестных типах уведомлений и об ошибках уведомлений, это позволит максимально быстро локализовать проблему и даст больше информации оператору, не пропустив еще неподдерживаемые типы уведомлений интеграцией.

Обязательно логируйте данные по уведомлениям, в записи должна содержаться информация включая дату и время получения - timestamp, тип уведомления - typeWebhook и остальные данные уведомления. Это позволит вам проводить анализ работы, при неожиданных сценариях работы системы.

5. Масштабирование и распределение нагрузки#

При увеличении размера системы Вы можете столкнуться с проблемой масштабирования. Рекомендуется масштабировать систему, распределяя нагрузку на несколько микросервисов обработчиков. Для этого можно использовать балансировщик нагрузки.

В качестве примера балансировщика приведем веб-сервер nginx, Вы можете использовать несколько экземпляров вашего сервера и распределять нагрузку между ними, используя nginx.

Nginx - это высокопроизводительный веб-сервер, который также может использоваться в качестве балансировщика нагрузки (процесс равномерного распределения веб-трафика между несколькими серверами), предотвращая перегрузку одного сервера. Nginx применяет различные алгоритмы для оптимального распределения трафика и может быть настроен для обеспечения надежности системы при выходе из строя одного или нескольких серверов.

Воспользуйтесь одним из приведённых способов, чтобы развернуть несколько экземпляров сервера:

Ручное развертывание на разных серверах или виртуальных машинах:#

• Создайте или арендуйте несколько физических серверов, виртуальных машин или контейнеров.
• Настройте каждый сервер так, чтобы он содержал копию вашего приложения.

Использование контейнеризации с Docker:#

• Создайте Docker-образ вашего приложения.
• Запустите несколько контейнеров с этим образом на одном или нескольких хост-машинах.

Использование облачных провайдеров:#

• Разверните несколько экземпляров вашего сервера на платформе облачных провайдеров, таких как Amazon Web Services (AWS), Google Cloud Platform (GCP) или Microsoft Azure.
• Используйте инструменты управления облачной инфраструктурой для автоматизации развертывания и масштабирования серверов.

http {
   upstream app{
      server 10.2.0.100;
      server 10.2.0.101;
      server 10.2.0.102;
   }

   // Этот сервер принимает весь трафик на порт 80 и передает его вышестоящему потоку.
   // Обратите внимание, что имя вышестоящего потока и proxy_pass должны совпадать.

   server {
      listen 80;

      server_name mydomain.com;

      location / {
         include proxy_params;

         proxy_pass http://app;


         proxy_redirect off;
         proxy_http_version 1.1;
         proxy_set_header Upgrade $http_upgrade;
         proxy_set_header Connection "upgrade";
      }
   }
}