Входящий вебхук

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.

Настройка

Откройте решение в приложении и перейдите на его вкладку Дополнительно:

  1. Включите вебхук. Dcision создаёт URL: https://api.dcision.io/v1/hooks/whk_, за которым следуют 32 буквы и цифры. Скопируйте его.
  2. Создайте секрет (рекомендуется). Полное значение whsec_… показывается только один раз — сохраните его там, где его сможет прочитать вызывающая сторона, например как DCISION_WEBHOOK_SECRET.
  3. Отправьте тест из консоли на вкладке: 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 } }
Сырой payload
{ "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_… или соберите тело в коде:

Node.js 18+
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:

200 OK
{
  "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" } }.

СтатусКодКогда
400INVALID_REQUESTПустое тело, тело, не являющееся корректным JSON, некорректное тело multipart/form-data или часть state, не являющаяся JSON-объектом.
401UNAUTHORIZEDУ вебхука есть секрет, а у вызова нет корректного доказательства: нет ни Dcision-Signature, ни Authorization, подпись некорректна или неверна, метка времени вне 300-секундного окна или неверный Bearer-секрет. Сообщение указывает, что именно.
402CREDITS_EXHAUSTEDВключённый в тариф объём израсходован, и кредитов не осталось.
402SPEND_CAP_REACHEDДостигнут лимит расходов за цикл оплаты.
402QUOTA_EXCEEDEDВключённый объём тарифа с жёстким ограничением израсходован.
404NOT_FOUNDНеизвестный токен, сменённый URL или выключенный вебхук.
409DECISION_NOT_DEPLOYEDРешение ни разу не публиковалось.
409DECISION_DISABLEDЭндпоинт решения отключён.
413PAYLOAD_TOO_LARGEТело больше 32 MB.
422INVALID_STATEState не соответствует схеме state решения или бюджету токенов движка, state без файлов больше 128 KB, файл больше 20 MB или файлов больше 10.
429RATE_LIMITEDМинутный лимит вебхуков рабочего пространства исчерпан (собственное окно, отдельное от API-ключей) — или вебхук получил за эту минуту больше 30 вызовов с неверной подписью или секретом (Retry-After: 60).
424, 5xxENGINE_…, INTERNAL_ERRORКак в разделе Запуск решения.

Отклонённые вызовы — неверная подпись, некорректный JSON, лимит запросов — не становятся выполнениями, но появляются в списке последних вызовов на вкладке «Дополнительно», так что вы видите, что отправляет неправильно настроенный инструмент.

Кто видит URL

Без секрета один только URL запускает решение — с оплатой и с реальными назначениями. Поэтому вкладка Дополнительно показывает его только участникам и администраторам; наблюдатели видят, что вебхук существует, но не видят его URL. Смена URL и управление секретом доступны администраторам. Когда кто-то уходит из команды, смените URL (и секрет), которые он мог видеть.

Кнопка Отправить тестовый запрос тоже работает в боевом режиме (назначения срабатывают по-настоящему) и считается выполнением через вебхук. В показываемом ею запросе подпись замаскирована, поэтому его нельзя воспроизвести.

На этой странице