Входящий вебхук
POST /v1/hooks/{token} — запуск опубликованного решения по секретному URL без API-ключа из форм, CRM, Zapier, n8n, Make или любого бэкенда, по желанию с подписью секретом whsec_.
POST https://api.dcision.io/v1/hooks/whk_…У каждого решения может быть URL вебхука: секретный адрес, который запускает активную версию решения, когда на него что-то отправляют POST-запросом, — форма, CRM, Zapier, n8n, Make, Pipedream или другой бэкенд. Ему не нужен API-ключ, поэтому решение могут запускать инструменты, которые умеют только вызывать URL, а добавив секрет, вы будете принимать только тех, кто его знает.
Входящий вебхук — входящий: кто-то вызывает Dcision. Назначения-вебхуки работают в обратную сторону — Dcision вызывает вас после того, как принял решение, — и используют событие decision.completed.
Настройка
Откройте решение в приложении и перейдите на его вкладку Дополнительно:
- Включите вебхук. Dcision создаёт URL:
https://api.dcision.io/v1/hooks/whk_, за которым следуют 32 буквы и цифры. Скопируйте его. - Создайте секрет (рекомендуется). Полное значение
whsec_…показывается только один раз — сохраните его там, где его сможет прочитать вызывающая сторона, например какDCISION_WEBHOOK_SECRET. - Отправьте тест из консоли на вкладке: Dcision вызывает настоящий URL с подписью секретом и показывает запрос и ответ. Тест выполняет решение как любой вызывающий и считается запуском.
Вкладка также показывает последние вызовы по мере их поступления, включая отклонённые, и содержит готовые фрагменты кода на cURL, Node.js и Python с вашим URL. Для включения и выключения вебхука нужна роль Участник; для смены URL и создания, замены или удаления секрета — Администратор, — см. Команда и роли.
URL выполняет опубликованную версию: опубликуйте решение, прежде чем направлять на него систему.
Запрос
Путь
| Параметр | Описание |
|---|---|
token | Токен whk_… вебхука решения. Он определяет и решение, и рабочее пространство. |
Параметры запроса
| Параметр | Описание |
|---|---|
include | Необязательно. probabilities добавляет полное распределение по каждому вопросу, как в разделе Запуск решения. |
Заголовки
| Заголовок | Обязателен | Описание |
|---|---|---|
Content-Type | Рекомендуется | application/json (любое другое значение тоже читается как JSON), text/plain, чтобы отправить текстовый state как есть, или multipart/form-data, чтобы загрузить файлы, — см. Отправка файлов. |
Dcision-Signature | При наличии секрета | t=<unix seconds>,v1=<hex> — см. Подпись запроса. |
Authorization | При наличии секрета, вместо подписи | Bearer whsec_… — сам секрет, для инструментов, которые не умеют вычислять HMAC. |
Idempotency-Key для URL вебхуков не поддерживается: повторный вызов выполняется — и тарифицируется — снова.
Тело
Отправьте state в обёртке, как для API, или сам payload:
{ "state": { "message": "Can I get a demo next week?", "company_size": 80 } }{ "message": "Can I get a demo next week?", "company_size": 80 }Когда тело — JSON-объект, единственный ключ которого state, Dcision использует значение state. Всё остальное — объект с другими ключами, массив, строка — и есть state. Это позволяет стороннему инструменту отправлять свой payload без изменений; его поля всё равно должны соответствовать схеме state решения.
Payload с единственным полем state
Если подключаемая система отправляет что-то вроде { "state": "CA" } — поле, которое случайно называется state, и больше ничего, — Dcision разворачивает его, и state становится "CA". Оборачивайте такие payload сами: { "state": { "state": "CA" } }.
Тело должно быть не больше 32 MB, чтобы state мог содержать файлы — до 20 MB каждый, 24 MB вместе. State без файлов по-прежнему должен укладываться в 128 KB; сверх этого вызов отвечает 422 INVALID_STATE.
Отправка файлов
Чтобы отправить фото, голосовое сообщение или документ, отправьте POST-запрос с multipart/form-data — именно это отправляют HTML-форма, n8n, Make или Zapier при загрузке файла. Dcision собирает state из частей:
| Часть | Становится |
|---|---|
| Текстовое поле | Строковым полем state с тем же именем. |
| Файл | Файлом в поле с тем же именем: { "data", "filename", "mime_type" }, как описано во Входных данных. Объявите это поле как image, audio или file. |
Поле с именем state | Необязательно. JSON-объект, с которого начинается state; остальные части добавляются к нему и заменяют его поля с тем же именем. |
curl https://api.dcision.io/v1/hooks/whk_… \
-F state='{"message":"Can we pay this?"}' \
-F invoice=@invoice.pdfПоля формы всегда строки: поле number или boolean схемы state, отправленное как поле формы, не проходит проверку (422 INVALID_STATE). Помещайте такие поля в часть state. Пустое файловое поле формы игнорируется. JSON-тело тоже может содержать файлы — в base64 или как URL https://, — см. Входные данные.
Подпись запроса
При наличии секрета каждый вызов должен доказать, что знает его, одним из двух способов.
Dcision-Signature (рекомендуется) — та же схема, которой Dcision подписывает свои собственные доставки вебхуков:
signed_payload = "<t>." + <the raw request body>
v1 = hex( HMAC-SHA256( secret, signed_payload ) )
header = Dcision-Signature: t=<t>,v1=<v1>t — текущее время Unix в секундах; вызовы, у которых t отличается от часов Dcision более чем на 300 секунд, отклоняются, поэтому перехваченный запрос нельзя воспроизвести позже. Подписывайте ровно те байты, которые отправляете, — сериализуйте тело один раз и используйте эту строку повторно. Для тела multipart/form-data HMAC вычисляется над "<t>.", за которым следуют сырые байты тела, включая границы и файлы, — см. Подпись multipart-тела.
Authorization: Bearer whsec_… — сам секрет, сравниваемый за постоянное время. Это проще для no-code-инструментов, но секрет передаётся с каждым запросом, а перехваченный запрос можно воспроизвести; если можете вычислить подпись, предпочитайте её. Достаточно любого из доказательств: если ваш инструмент добавляет собственный заголовок Authorization (свои учётные данные, токен API-шлюза), корректная Dcision-Signature всё равно проходит.
URL="https://api.dcision.io/v1/hooks/whk_…" # from the Advanced tab
BODY='{"state":{"message":"Can I get a demo next week?","company_size":80}}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$DCISION_WEBHOOK_SECRET" | sed 's/^.* //')
curl -X POST "$URL" \
-H "Content-Type: application/json" \
-H "Dcision-Signature: t=$TS,v1=$SIG" \
-d "$BODY"В Zapier, n8n или Make используйте шаг HTTP или webhook с методом POST, URL, JSON-телом и заголовком Authorization = Bearer whsec_…, сохранённым как учётные данные.
Подпись multipart-тела
Сначала соберите multipart-тело, подпишите его байты, затем отправьте те же байты с тем же Content-Type (в нём указана граница). С curl -F тело собирает сам curl, поэтому подписать его заранее нельзя: используйте там Authorization: Bearer whsec_… или соберите тело в коде:
import crypto from "node:crypto";
import { readFile } from "node:fs/promises";
const url = process.env.DCISION_WEBHOOK_URL; // https://api.dcision.io/v1/hooks/whk_…
const form = new FormData();
form.append("state", JSON.stringify({ message: "Can we pay this?" }));
form.append("invoice", new Blob([await readFile("invoice.pdf")], { type: "application/pdf" }), "invoice.pdf");
// Serialize the form once: these bytes are signed and sent.
const encoded = new Request(url, { method: "POST", body: form });
const body = Buffer.from(await encoded.arrayBuffer());
const t = Math.floor(Date.now() / 1000);
const v1 = crypto.createHmac("sha256", process.env.DCISION_WEBHOOK_SECRET).update(`${t}.`).update(body).digest("hex");
const response = await fetch(url, {
method: "POST",
headers: { "Content-Type": encoded.headers.get("content-type"), "Dcision-Signature": `t=${t},v1=${v1}` },
body,
});
console.log(response.status, await response.json());Без секрета
Вебхук без секрета принимает любой вызов своего URL: учётными данными служит сам URL. Это нормально для быстрого теста или доверенной внутренней сети, но любой, кто увидит URL — в журналах инструмента, на общем скриншоте, в истории браузера, — может запустить решение, и каждый запуск оплачивается вашим рабочим пространством.
- Добавьте секрет, прежде чем указывать URL в стороннем инструменте, и не помещайте секрет в URL.
- Если URL утёк, смените его на вкладке «Дополнительно»: старый URL сразу перестаёт работать и отвечает
404. - Выключение вебхука заставляет URL отвечать
404 NOT_FOUND— так же, как URL, которого никогда не было.
Удаление секрета снова заставляет URL принимать неподписанные вызовы.
Ответ
Тот же ответ, что и у POST /v1/decisions/{slug}, — result, confidence, scores, composites, action, action_reason, destinations и metrics:
{
"decision_id": "dec_3fKq9ZtW1mXcV7bN2pLa",
"execution_id": "exec_8HsT2kQw9ZyR4vMn1cXe",
"schema": "lead-qualification",
"version": 1,
"result": { "purchase_intent": 0.9412, "priority": "high", "route": "sales" },
"confidence": { "purchase_intent": 0.8824, "priority": 0.69, "route": 0.85 },
"scores": { "priority": 2.81 },
"composites": { "lead_score": 0.8414 },
"action": "continue",
"action_reason": { "type": "default" },
"metrics": {
"latency_ms": 412,
"engine": "jev",
"model": "jev-1.13.0",
"estimated_cost_usd": 0.00001575,
"input_tokens": 375,
"output_tokens": 36
}
}Запуски через URL вебхука:
- тарифицируются как вызовы API и учитываются во включённом в тариф объёме — сверх него они расходуют кредиты, а без кредитов отвечают
402 CREDITS_EXHAUSTED; - делят с API лимит запросов решений рабочего пространства — см. Лимиты запросов;
- выполняют назначения решения с
livemode: true; - появляются в Выполнениях, на вкладке Обзор решения вместе с API-трафиком и в
GET /v1/executionsсsource: "webhook".
Ошибки
Ошибки используют стандартный формат, { "error": { "code", "message", "request_id" } }.
| Статус | Код | Когда |
|---|---|---|
| 400 | INVALID_REQUEST | Пустое тело, тело, не являющееся корректным JSON, некорректное тело multipart/form-data или часть state, не являющаяся JSON-объектом. |
| 401 | UNAUTHORIZED | У вебхука есть секрет, а у вызова нет корректного доказательства: нет ни Dcision-Signature, ни Authorization, подпись некорректна или неверна, метка времени вне 300-секундного окна или неверный Bearer-секрет. Сообщение указывает, что именно. |
| 402 | CREDITS_EXHAUSTED | Включённый в тариф объём израсходован, и кредитов не осталось. |
| 402 | SPEND_CAP_REACHED | Достигнут лимит расходов за цикл оплаты. |
| 402 | QUOTA_EXCEEDED | Включённый объём тарифа с жёстким ограничением израсходован. |
| 404 | NOT_FOUND | Неизвестный токен, сменённый URL или выключенный вебхук. |
| 409 | DECISION_NOT_DEPLOYED | Решение ни разу не публиковалось. |
| 409 | DECISION_DISABLED | Эндпоинт решения отключён. |
| 413 | PAYLOAD_TOO_LARGE | Тело больше 32 MB. |
| 422 | INVALID_STATE | State не соответствует схеме state решения или бюджету токенов движка, state без файлов больше 128 KB, файл больше 20 MB или файлов больше 10. |
| 429 | RATE_LIMITED | Минутный лимит вебхуков рабочего пространства исчерпан (собственное окно, отдельное от API-ключей) — или вебхук получил за эту минуту больше 30 вызовов с неверной подписью или секретом (Retry-After: 60). |
| 424, 5xx | ENGINE_…, INTERNAL_ERROR | Как в разделе Запуск решения. |
Отклонённые вызовы — неверная подпись, некорректный JSON, лимит запросов — не становятся выполнениями, но появляются в списке последних вызовов на вкладке «Дополнительно», так что вы видите, что отправляет неправильно настроенный инструмент.
Кто видит URL
Без секрета один только URL запускает решение — с оплатой и с реальными назначениями. Поэтому вкладка Дополнительно показывает его только участникам и администраторам; наблюдатели видят, что вебхук существует, но не видят его URL. Смена URL и управление секретом доступны администраторам. Когда кто-то уходит из команды, смените URL (и секрет), которые он мог видеть.
Кнопка Отправить тестовый запрос тоже работает в боевом режиме (назначения срабатывают по-настоящему) и считается выполнением через вебхук. В показываемом ею запросе подпись замаскирована, поэтому его нельзя воспроизвести.
API сессий встраивания
POST /v1/embed/sessions — открывает встраиваемый редактор для одного из ваших конечных пользователей в его подпространстве; отзыв сессий. Только на стороне сервера.
События вебхуков
Событие decision.completed из документа OpenAPI — запрос, отправляемый назначениям-вебхукам, его заголовки, каждое поле события и ответы, которых ожидает Dcision.