Настройки вебхуков

Интеграция типа webhook подписывается на набор событий платформы (см. справочник событий вебхуков) и при их наступлении отправляет POST-запрос с подписанным телом на указанный URL. Через эту группу вы создаёте и настраиваете исходящие вебхуки AISAR, управляете их секретами и читаете логи доставки. Bitrix24 и amoCRM подключаются отдельными OAuth-флоу через кабинет my.aisar.app и в этот справочник не входят.

Аутентификация, ретраи и фильтры

Поддерживаются bearer/basic-аутентификация на стороне получателя, ретраи с ограничением попыток и фильтр по каналам.

Каталог провайдеров и сводка

Каталог доступных провайдеров возвращает GET /v1/integration-providers, сводку активных интеграций по типу — GET /v1/integrations/summary.

Источник событий

Ключи событий для поля selectedEventKeys берутся из каталога системных событий GET /v1/system-events — это единый источник событий, на которые может подписаться вебхук (полные схемы полезной нагрузки — в справочнике событий вебхуков).

Ротация секретов

Секреты интеграции (signingSecret, bearerToken, basicUsername, basicPassword) ротируются через PATCH с новым объектом secrets; в ответе обновляется credential.rotated_at.

Эндпоинты

Метод	Путь	Описание
GET	`/v1/integrations` Список интеграций (фильтр по type, status)	Список интеграций (фильтр по type, status)
POST	`/v1/integrations` Создание вебхук-интеграции	Создание вебхук-интеграции
GET	`/v1/integrations/{integration}` Получение интеграции (с credential и mappings)	Получение интеграции (с credential и mappings)
PATCH	`/v1/integrations/{integration}` Обновление интеграции	Обновление интеграции
DELETE	`/v1/integrations/{integration}` Удаление интеграции	Удаление интеграции
GET	`/v1/integrations/{integration}/logs` Логи доставки вебхуков	Логи доставки вебхуков
POST	`/v1/integrations/test-webhook` Тестовая отправка на указанный URL (без сохранения интеграции)	Тестовая отправка на указанный URL (без сохранения интеграции)
GET	`/v1/integration-providers` Каталог провайдеров интеграций (query: published)	Каталог провайдеров интеграций (query: published)
GET	`/v1/integrations/summary` Сводка интеграций по типу	Сводка интеграций по типу
GET	`/v1/system-events` Каталог системных событий — источник ключей событий для вебхуков (query: type, group)	Каталог системных событий — источник ключей событий для вебхуков (query: type, group)

Примеры

Создание вебхук-интеграции

Запрос

bash

curl -X POST https://api.aisar.app/v1/integrations \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "webhook",
    "name": "n8n Production",
    "status": "active",
    "settings": {
      "url": "https://example.com/webhook",
      "authType": "bearer",
      "selectedEventKeys": ["message.created", "conversation.created"],
      "channelFilter": "all",
      "timeoutSeconds": 30,
      "retryEnabled": true,
      "maxAttempts": 6
    },
    "secrets": { "bearerToken": "your-receiving-endpoint-secret" }
  }'

Ответ

json

{
  "data": {
    "id": 14,
    "type": "webhook",
    "name": "n8n Production",
    "status": "active",
    "health": {
      "last_success_at": null,
      "last_failure_at": null,
      "last_error": null,
      "consecutive_failures": 0
    },
    "settings": {
      "url": "https://example.com/webhook",
      "authType": "bearer",
      "selectedEventKeys": ["message.created", "conversation.created"],
      "channelFilter": "all",
      "timeoutSeconds": 30,
      "retryEnabled": true,
      "maxAttempts": 6
    },
    "credential": {
      "secrets": { "bearerToken": "your-receiving-endpoint-secret" },
      "expires_at": null,
      "last_refreshed_at": null,
      "rotated_at": null,
      "created_at": "2026-03-15T10:00:00.000000Z",
      "updated_at": "2026-03-15T10:00:00.000000Z"
    },
    "external_entities": [],
    "mappings": [],
    "funnel_mappings": [],
    "created_at": "2026-03-15T10:00:00.000000Z",
    "updated_at": "2026-03-15T10:00:00.000000Z"
  }
}

Логи доставки вебхука

Запрос

bash

curl "https://api.aisar.app/v1/integrations/14/logs?limit=50" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ

json

{
  "data": [
    {
      "id": 8801,
      "level": "info",
      "code": "webhook.delivery",
      "message": "Webhook delivered.",
      "context": {
        "event_key": "message.created",
        "status": "success",
        "status_code": 200,
        "duration_ms": 420
      },
      "created_at": "2026-03-15T10:05:00.000000Z"
    }
  ]
}

Каталог провайдеров интеграций

Запрос

bash

curl "https://api.aisar.app/v1/integration-providers?published=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ

json

{
  "data": [
    {
      "id": 1,
      "key": "webhook",
      "name": "Webhook",
      "description": "Outbound webhook integration",
      "is_published": true,
      "created_at": "2026-03-01T09:00:00.000000Z",
      "updated_at": "2026-03-01T09:00:00.000000Z"
    },
    {
      "id": 2,
      "key": "bitrix24",
      "name": "Bitrix24",
      "description": "Bitrix24 CRM connector",
      "is_published": true,
      "created_at": "2026-03-01T09:00:00.000000Z",
      "updated_at": "2026-03-01T09:00:00.000000Z"
    }
  ]
}

Сводка интеграций по типу

Запрос

bash

curl "https://api.aisar.app/v1/integrations/summary" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ

json

{
  "data": [
    { "type": "webhook", "count": 2 },
    { "type": "bitrix24", "count": 1 }
  ]
}

Ротация секретов интеграции (переход на basic-auth)

Запрос

bash

curl -X PATCH https://api.aisar.app/v1/integrations/14 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "url": "https://example.com/webhook",
      "description": "Production automation",
      "signatureHeader": "X-AISAR-Signature",
      "authType": "basic",
      "selectedEventKeys": ["message.created", "conversation.created"],
      "channelFilter": "all",
      "timeoutSeconds": 30,
      "retryEnabled": true,
      "maxAttempts": 6,
      "concurrency": 4
    },
    "secrets": {
      "signingSecret": "YOUR_SIGNING_SECRET",
      "basicUsername": "webhook-user",
      "basicPassword": "YOUR_BASIC_PASSWORD"
    }
  }'

Ответ

json

{
  "data": {
    "id": 14,
    "type": "webhook",
    "name": "n8n Production",
    "status": "active",
    "settings": {
      "url": "https://example.com/webhook",
      "description": "Production automation",
      "signatureHeader": "X-AISAR-Signature",
      "authType": "basic",
      "selectedEventKeys": ["message.created", "conversation.created"],
      "channelFilter": "all",
      "timeoutSeconds": 30,
      "retryEnabled": true,
      "maxAttempts": 6,
      "concurrency": 4
    },
    "credential": {
      "secrets": {
        "signingSecret": "YOUR_SIGNING_SECRET",
        "basicUsername": "webhook-user",
        "basicPassword": "YOUR_BASIC_PASSWORD"
      },
      "expires_at": null,
      "last_refreshed_at": null,
      "rotated_at": "2026-03-16T08:30:00.000000Z",
      "created_at": "2026-03-15T10:00:00.000000Z",
      "updated_at": "2026-03-16T08:30:00.000000Z"
    },
    "external_entities": [],
    "mappings": [],
    "funnel_mappings": [],
    "created_at": "2026-03-15T10:00:00.000000Z",
    "updated_at": "2026-03-16T08:30:00.000000Z"
  }
}

Системные события — источник событий вебхуков

Запрос

bash

curl "https://api.aisar.app/v1/system-events?group=Messages" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ

json

{
  "data": [
    {
      "id": 1,
      "key": "message.created",
      "type": "message",
      "name": "Message created",
      "description": "A new message is created in a conversation.",
      "group": "Messages",
      "metadata": {},
      "created_at": "2026-03-01T09:00:00.000000Z",
      "updated_at": "2026-03-01T09:00:00.000000Z"
    },
    {
      "id": 2,
      "key": "message.updated",
      "type": "message",
      "name": "Message updated",
      "description": "A message is edited.",
      "group": "Messages",
      "metadata": {},
      "created_at": "2026-03-01T09:00:00.000000Z",
      "updated_at": "2026-03-01T09:00:00.000000Z"
    }
  ]
}