Вебхуки

Вебхук — ваш адрес, на который Voice AI отправляет POST-запрос, когда происходит событие.

События

Событие	Когда	Поле `data`
`audio-transcribed`	Звонок расшифрован	`callId`, `transcriptionId`
`scenario-{id}-done`	Сценарий с этим ID выполнен, например `scenario-42-done`	`callId`, `scenarioId`, `analyseId`

Формат доставки

POST /your/hook HTTP/1.1
Content-Type: application/json

{
    "event": "audio-transcribed",
    "amocrmId": 31245678,
    "occurredAt": "2026-10-19T11:05:12.444Z",
    "data": { "callId": "245581", "transcriptionId": "4210" }
}

Как принимать доставки

ответьте кодом 2xx в течение 10 секунд, иначе доставка считается неуспешной;
доставка выполняется один раз, повторных попыток нет. Если событие важно не пропустить, сверяйтесь со списком звонков по hasTranscription и analyses;
запросы не подписываются. Используйте адрес, который трудно подобрать, и проверяйте amocrmId в теле;
событие несёт только идентификаторы. Сами данные запросите методами расшифровки и результатов.

Объект вебхука

{
    "id": "9",
    "amocrmId": 31245678,
    "active": true,
    "name": "Выгрузка в хранилище",
    "url": "https://example.com/hooks/voice-ai",
    "events": ["audio-transcribed", "scenario-42-done"],
    "lastResult": {
        "success": true,
        "status": 200,
        "error": null,
        "durationMs": 184,
        "deliveredAt": "2026-10-19T11:05:12.630Z"
    },
    "createdAt": "2026-10-01T09:00:00.000Z",
    "updatedAt": "2026-10-19T11:05:12.630Z",
    "deletedAt": null
}

lastResult — итог последней доставки: status — код ответа вашего сервера (null, если ответа не было), error — текст ошибки, durationMs — время ответа. У вебхука без доставок lastResult равен null.

Список вебхуков

GET /api/v1/settings/webhooks/{amocrmId}

Ответ 200 — массив объектов вебхука. Удалённые вебхуки не возвращаются.

Создать вебхук

POST /api/v1/settings/webhooks

Тело запроса

Поле	Тип	Описание
`amocrmId` обязательное	int	Аккаунт amoCRM
`name` обязательное	string	Название, до 255 символов
`url` обязательное	string	Адрес для доставки, до 2048 символов
`events` обязательное	string[]	Непустой список событий
`active`	bool	Включён ли вебхук. По умолчанию `true`

curl -X POST "{base_url}/api/v1/settings/webhooks" \
  -H "Content-Type: application/json" \
  -d '{
    "amocrmId": 31245678,
    "name": "Выгрузка в хранилище",
    "url": "https://example.com/hooks/voice-ai",
    "events": ["audio-transcribed", "scenario-42-done"]
  }'

Ответ 201 — созданный объект вебхука. Ошибка 400 — неверное поле или неподдерживаемое событие.

Изменить вебхук

PATCH /api/v1/settings/webhooks/{webhookId}

Тело — любые из полей name, url, events, active; должно быть передано хотя бы одно. Меняются только переданные поля.

Ответ 200 — обновлённый объект вебхука. Ошибки: 400 — неверное поле или пустое тело; 404 — вебхука нет.

Удалить вебхук

DELETE /api/v1/settings/webhooks/{webhookId}

Ответ `200`

{ "ok": true, "data": 1 }

После удаления вебхук перестаёт получать события и пропадает из списка; его история доставок остаётся доступной. Ошибка 404 — вебхука нет.

История доставок

GET /api/v1/settings/webhooks/{amocrmId}/events

Возвращает доставки аккаунта, от новых к старым.

Параметры запроса

Параметр	Тип	Описание
`webhookId`	string	Только доставки этого вебхука
`callId`	string	Только доставки по этому звонку

{
    "ok": true,
    "data": [
        {
            "id": "5561",
            "webhookId": "9",
            "callId": "245581",
            "eventName": "audio-transcribed",
            "status": 200,
            "result": 184,
            "createdAt": "2026-10-19T11:05:12.630Z",
            "webhook": { "id": "9", "name": "Выгрузка в хранилище", "url": "https://example.com/hooks/voice-ai" },
            "call": { "id": "245581", "type": "call_in", "duration": 52 }
        }
    ]
}

Поле	Тип	Описание
`eventName`	string	Доставленное событие
`status`	int	Код ответа вашего сервера; `0` — ответа не было
`result`	int	Время ответа в миллисекундах
`webhook`	object \| null	Объект вебхука целиком (в примере сокращён)
`call`	object \| null	Звонок в формате v1 целиком (в примере сокращён); `null`, если событие не связано со звонком