Webhook¶

Webhook-интеграция отправляет уведомления во внешнюю систему при тестировании интеграции или срабатывании триггера.
Тело запроса передаётся в формате JSON. Структура JSON зависит от типа события.
Значения идентификаторов, имён, email, IP-адресов и доменов в примерах являются демонстрационными.

Особенности¶

• В рабочих уведомлениях timestamp содержит Unix timestamp в секундах.

• Тип системного события определяется полем event_type.

• Тип изменения структуры API определяется верхнеуровневым полем change_type.

• Поля node_link, trigger_link и integration_link содержат относительные ссылки.

• Порядок полей в JSON не гарантируется.

• В новые версии уведомлений могут добавляться поля. Принимающей системе рекомендуется игнорировать неизвестные поля.

• Уведомление считается принятым, если принимающая система вернула HTTP-код 2xx.

Webhook может содержать имена, email и IP-адреса пользователей.
Учитывайте это при выборе принимающей системы, настройке доступа и журналировании запросов.

Тестирование интеграции¶

При нажатии кнопки Протестировать отправляется следующий JSON:

    {
    "message": "API Firewall Manager webhook test",
    "test": true,
    "timestamp": "2026-08-24T13:54:58Z"
    }

Системные события¶

Большинство системных событий содержит:

• user_id – идентификатор пользователя, выполнившего действие

• caused_by_username и caused_by_email – данные пользователя, выполнившего действие

• client_name – название клиента

• timestamp – время события

• event_type – тип события

События аутентификации имеют отдельную структуру.

Создание, изменение и удаление ноды¶

Поддерживаемые значения event_type:

• node_create

• node_change

• node_delete

    {
    "user_id": "u-123",
    "event_type": "node_create",
    "node_name": "node-1",
    "node_link": "/nodes/1",
    "timestamp": 1711447300,
    "caused_by_username": "Alice Example",
    "caused_by_email": "alice@example.com",
    "client_name": "Acme"
    }

Создание, изменение и удаление приложения¶

Поддерживаемые значения event_type:

• application_create

• application_change

• application_delete

{
  "user_id": "u-123",
  "event_type": "application_change",
  "application_id": 101,
  "application_name": "billing",
  "spec_name": "openapi.yaml",
  "timestamp": 1711447300,
  "old_params": {
    "name": "old-name"
  },
  "changed_params": {
    "name": "new-name"
  },
  "caused_by_username": "Alice Example",
  "caused_by_email": "alice@example.com",
  "client_name": "Acme"
}

Особенности:

• spec_name содержит название API-спецификации и может принимать null

• old_params содержит значения параметров до изменения

• changed_params содержит значения параметров после изменения

• Состав old_params и changed_params зависит от выполненного действия

Очистка структуры API¶

Событие отправляется с event_type: "clear_endpoints".

{
  "user_id": "u-123",
  "event_type": "clear_endpoints",
  "application_id": 101,
  "application_name": "billing",
  "spec_name": null,
  "clear_endpoints": true,
  "timestamp": 1711447300,
  "caused_by_username": "Alice Example",
  "caused_by_email": "alice@example.com",
  "client_name": "Acme"
}

Создание и удаление пользователя¶

Поддерживаемые значения event_type:

• create_user

• delete_user
  

  {
    "user_id": "u-123",
    "event_type": "create_user",
    "user_name": "Bob Smith",
    "user_email": "bob@example.com",
    "role": "admin",
    "timestamp": 1711447300,
    "caused_by_username": "Alice Example",
    "caused_by_email": "alice@example.com",
    "client_name": "Acme"
  }
  

  
  Поля user_name, user_email и role относятся к пользователю, над которым выполнено действие. Поля caused_by_username и caused_by_email относятся к пользователю, выполнившему действие.

Изменение пользователя¶

Событие отправляется с event_type: "user_change".

{
  "user_id": "u-123",
  "event_type": "user_change",
  "user_name": "Bob Smith",
  "user_email": "bob@example.com",
  "old_role": "viewer",
  "new_role": "admin",
  "timestamp": 1711447300,
  "changed_attributes": [
    "role"
  ],
  "caused_by_username": "Alice Example",
  "caused_by_email": "alice@example.com",
  "client_name": "Acme"
}

Особенности:

• old_role содержит роль до изменения

• new_role содержит роль после изменения

• changed_attributes содержит список изменённых атрибутов

Включение и отключение пользователя¶

Событие отправляется с event_type: "user_toggle".

{
  "user_id": "u-123",
  "event_type": "user_toggle",
  "action": "enable",
  "user_name": "Bob Smith",
  "user_email": "bob@example.com",
  "role": "admin",
  "timestamp": 1711447300,
  "caused_by_username": "Alice Example",
  "caused_by_email": "alice@example.com",
  "client_name": "Acme"
}

Поле action содержит выполненное действие:

• enable – пользователь включён

• disable – пользователь отключён

События триггера¶

Поддерживаемые значения event_type:

• trigger_create

• trigger_change

• trigger_delete

• trigger_toggle

{
  "user_id": "u-123",
  "event_type": "trigger_change",
  "trigger_name": "Too many validation errors",
  "application_ids": [
    101,
    102
  ],
  "trigger_link": "/triggers/1",
  "timestamp": 1711447300,
  "caused_by_username": "Alice Example",
  "caused_by_email": "alice@example.com",
  "client_name": "Acme"
}

application_ids содержит идентификаторы приложений, связанных с триггером.
Событие trigger_toggle сообщает об изменении статуса триггера. Отдельное поле с новым статусом в уведомлении отсутствует.

События интеграции¶

Поддерживаемые значения event_type:

• integration_create

• integration_change

• integration_delete

• integration_toggle

{
  "user_id": "u-123",
  "event_type": "integration_change",
  "integration_name": "External webhook",
  "integration_type": "webhook",
  "integration_link": "/integrations/1",
  "timestamp": 1711447300,
  "caused_by_username": "Alice Example",
  "caused_by_email": "alice@example.com",
  "client_name": "Acme"
}

Событие integration_toggle сообщает об изменении статуса интеграции. Отдельное поле с новым статусом в уведомлении отсутствует.

События аутентификации¶

Успешный вход¶

Событие отправляется с event_type: "login_success".

{
  "event_type": "login_success",
  "user_name": "Alice Example",
  "user_email": "alice@example.com",
  "ip_address": "203.0.113.10",
  "timestamp": 1711447300
}

Неуспешный вход¶

Событие отправляется с event_type: "login_failure".

{
  "event_type": "login_failure",
  "user_email": "alice@example.com",
  "reason": "invalid password",
  "ip_address": "203.0.113.10",
  "timestamp": 1711447300
}

Изменение пароля¶

Событие отправляется с event_type: "password_change".

{
  "event_type": "password_change",
  "user_name": "Alice Example",
  "user_email": "alice@example.com",
  "timestamp": 1711447300
}

Изменение структуры API¶

Webhook отправляется при создании или изменении эндпоинта.
Поддерживаемые значения верхнеуровневого change_type:

• endpoint_created

• endpoint_changed

{
  "client_name": "Acme",
  "application": "billing",
  "domain": "api.example.com",
  "endpoint_path": "/v1/users/{id}",
  "http_method": "PATCH",
  "change_type": "endpoint_changed",
  "changed_parameters": [
    {
      "point": "request_body.email",
      "name": "email",
      "change_type": "added",
      "pii": [],
      "type": "string"
    },
    {
      "point": "query.expand",
      "name": "expand",
      "change_type": "removed",
      "pii": [],
      "type": "string"
    }
  ]
}

Особенности:

• верхнеуровневый change_type определяет тип изменения эндпоинта;

• changed_parameters[].change_type определяет тип изменения отдельного параметра;

• point содержит расположение параметра в запросе или ответе;

• pii содержит обнаруженные категории персональных или чувствительных данных;

• type содержит тип данных параметра.

Для endpoint_created в changed_parameters передаются все обнаруженные параметры нового эндпоинта с change_type: "added".

{
  "client_name": "Acme",
  "application": "billing",
  "domain": "api.example.com",
  "endpoint_path": "/v1/users",
  "http_method": "POST",
  "change_type": "endpoint_created",
  "changed_parameters": [
    {
      "point": "request_body.email",
      "name": "email",
      "change_type": "added",
      "pii": [],
      "type": "string"
    }
  ]
}

Если новый эндпоинт не содержит обнаруженных параметров, передаётся пустой массив:

{
  "changed_parameters": []
}

Количество событий за период¶

Webhook отправляется, когда количество событий выбранного типа превышает установленный порог за заданный период.

Поддерживаемые значения event_type:

• unknown_path – запрос к неизвестному эндпоинту

• request_validation_error – ошибка валидации входящего запроса

• response_validation_error – ошибка валидации ответа сервиса

• undefined_parameters – переданы параметры, отсутствующие в API-описании

• shadow_api – обнаружен Shadow API эндпоинт

• shadow_api_response – обнаружен ответ Shadow API

{
  "trigger_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "request_validation_error",
  "timestamp": 1711447300,
  "period": 300,
  "events_count": 25,
  "same_ip": true,
  "source_ip": "203.0.113.10"
}

Особенности:

• trigger_id содержит идентификатор сработавшего триггера

• period содержит период подсчёта событий в секундах

• events_count содержит количество событий за период

• same_ip показывает, учитывались ли события с одного IP-адреса

Если учитываются события с одного IP-адреса:

{
  "same_ip": true,
  "source_ip": "203.0.113.10"
}

{
  "same_ip": false,
  "source_ip": null
}