Перейти к содержанию

Вебхуки

InfraVision можно настроить через Правила событий для отправки исходящих вебхуков во внешние системы в ответ на изменения внутренних объектов. Получатель может действовать на основе данных в этих сообщениях вебхуков для выполнения связанных задач.

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

Предупреждение о безопасности

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

Поддержка шаблонов Jinja2

Шаблонизация Jinja2 поддерживается для полей URL, additional_headers и body_template. Это позволяет пользователю передавать данные объекта в заголовках запроса, а также создавать настроенное тело запроса. Содержимое запроса может быть сформировано для обеспечения прямого взаимодействия с внешними системами путём обеспечения того, чтобы исходящее сообщение было в формате, который получатель ожидает и понимает.

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

  • Тип объекта: IPAM > IP-адрес
  • HTTP-метод: POST
  • URL: URL входящего вебхука Slack
  • Тип контента HTTP: application/json
  • Шаблон тела: {"text": "IP-адрес {{ data['address'] }} был создан пользователем {{ username }}!"}

Доступный контекст

Следующие данные доступны как контекст для шаблонов Jinja2:

  • event - Тип события, которое вызвало вебхук: created, updated или deleted.
  • model - Модель InfraVision, которая вызвала изменение.
  • timestamp - Время, когда произошло событие (в формате ISO 8601).
  • username - Имя учётной записи пользователя, связанной с изменением.
  • request_id - Уникальный идентификатор запроса. Может использоваться для корреляции нескольких изменений, связанных с одним запросом.
  • data - Подробное представление объекта в его текущем состоянии. Обычно это эквивалентно представлению модели в REST API InfraVision.
  • snapshots - Минимальные "снимки" состояния объекта до и после внесения изменения; предоставляются как словарь с ключами prechange и postchange. Они не такие обширные, как полностью сериализованное представление, но содержат достаточно информации, чтобы передать, что изменилось.

Тело запроса по умолчанию

Если шаблон тела не указан, тело запроса будет заполнено JSON-объектом, содержащим контекстные данные. Например, вновь созданная площадка может выглядеть следующим образом:

{
    "event": "created",
    "timestamp": "2021-03-09 17:55:33.968016+00:00",
    "model": "site",
    "username": "jstretch",
    "request_id": "fdbca812-3142-4783-b364-2e2bd5c16c6a",
    "data": {
        "id": 19,
        "name": "Site 1",
        "slug": "site-1",
        "status":
            "value": "active",
            "label": "Active",
            "id": 1
        },
        "region": null,
        ...
    },
    "snapshots": {
        "prechange": null,
        "postchange": {
            "created": "2021-03-09",
            "last_updated": "2021-03-09T17:55:33.851Z",
            "name": "Site 1",
            "slug": "site-1",
            "status": "active",
            ...
        }
    }
}

Примечание

Настройка условных вебхуков была перенесена в Правила событий начиная с InfraVision 3.7

Обработка вебхуков

Используя Правила событий, при обнаружении изменения любые результирующие вебхуки помещаются в очередь Redis для обработки. Это позволяет запросу пользователя завершиться без необходимости ожидания обработки исходящего(-их) вебхука(-ов). Затем вебхуки извлекаются из очереди процессом rqworker и HTTP-запросы отправляются на их соответствующие адреса назначения. Текущую очередь вебхуков и любые неудавшиеся вебхуки можно просмотреть в разделе Система > Фоновые задачи.

Запрос считается успешным, если ответ имеет код статуса 2XX; в противном случае запрос помечается как неудавшийся. Неудавшиеся запросы могут быть вручную повторно поставлены в очередь в разделе Система > Фоновые задачи.

Устранение неполадок

Для помощи в проверке того, что содержимое исходящих вебхуков отрендерено корректно, InfraVision предоставляет простой HTTP-слушатель, который можно запустить локально для получения и отображения запросов вебхуков. Сначала измените целевой URL желаемого вебхука на http://localhost:9000/. Это проинструктирует InfraVision отправлять запрос на локальный сервер по TCP-порту 9000. Затем запустите службу приёмника вебхуков из корневого каталога InfraVision:

$ python netbox/manage.py webhook_receiver
Listening on port http://localhost:9000. Stop with CONTROL-C.

Вы можете протестировать сам приёмник, отправив ему любой HTTP-запрос. Например:

$ curl -X POST http://localhost:9000 --data '{"foo": "bar"}'

Сервер выведет вывод, похожий на следующий:

[1] Tue, 07 Apr 2020 17:44:02 GMT 127.0.0.1 "POST / HTTP/1.1" 200 -
Host: localhost:9000
User-Agent: curl/7.58.0
Accept: */*
Content-Length: 14
Content-Type: application/x-www-form-urlencoded

{"foo": "bar"}
------------

Обратите внимание, что webhook_receiver на самом деле не делает ничего с полученной информацией: он просто выводит заголовки и тело запроса для проверки. Если вы не видите никакого вывода, убедитесь, что процесс rqworker запущен и что события вебхуков помещаются в очередь.

Результаты вебхуков можно найти в административном интерфейсе InfraVision в разделе Фоновые задачи. Вы можете увидеть все завершённые или неудавшиеся запуски, а также журнал ошибок для неудавшихся вебхуков.