入站 webhook
POST /v1/hooks/{token}——无需 API 密钥,通过一个秘密 URL 运行已部署的决策,可从表单、CRM、Zapier、n8n、Make 或任何后端调用,并可选用 whsec_ 密钥签名。
POST https://api.dcision.io/v1/hooks/whk_…每个决策都可以有一个 webhook URL:一个秘密地址,当有东西向它发送 POST 请求时——表单、CRM、Zapier、n8n、Make、Pipedream 或其他后端——就会运行该决策的当前生效版本。它不需要 API 密钥,因此只能调用 URL 的工具也可以触发决策;你还可以添加一个签名密钥,只接受知道该密钥的调用方。
入站 webhook 是入站的:由别人调用 Dcision。Webhook 目的地的方向相反——Dcision 在做出决策后调用你——并使用 decision.completed 事件。
设置
在应用中打开决策,进入其高级标签页:
- 开启 webhook。 Dcision 会创建 URL:
https://api.dcision.io/v1/hooks/whk_加上 32 个字母和数字。复制它。 - 生成密钥(推荐)。完整的
whsec_…值只显示一次——把它保存在调用方可以读取的地方,例如保存为DCISION_WEBHOOK_SECRET。 - 从该标签页的控制台发送测试请求:Dcision 会用该密钥签名并调用真实的 URL,然后显示请求和响应。测试会像任何调用方一样运行决策,并计为一次运行。
该标签页还会实时列出最近的调用(包括被拒绝的调用),并提供带有你的 URL 的现成 cURL、Node.js 和 Python 代码片段。开启或关闭 webhook 需要 Member 角色;轮换 URL 以及生成、替换或移除密钥需要 Admin——参见团队与角色。
该 URL 运行的是已部署的版本:在让某个系统指向它之前,请先部署决策。
请求
路径
| 参数 | 描述 |
|---|---|
token | 决策 webhook 的 whk_… token。它同时标识决策和工作区。 |
查询参数
| 参数 | 描述 |
|---|---|
include | 可选。probabilities 会添加每个问题的完整分布,与运行决策中相同。 |
请求头
| 请求头 | 必填 | 描述 |
|---|---|---|
Content-Type | 推荐 | application/json(任何其他值也会按 JSON 读取)、用 text/plain 按原样发送文本状态,或用 multipart/form-data 上传文件——参见发送文件。 |
Dcision-Signature | 有密钥时 | t=<unix seconds>,v1=<hex>——参见为请求签名。 |
Authorization | 有密钥时,代替签名 | Bearer whsec_…——即密钥本身,供无法计算 HMAC 的工具使用。 |
webhook URL 不支持 Idempotency-Key:重试的调用会再次运行——并再次计费。
请求体
可以像调用 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 }当请求体是一个只有 state 一个键的 JSON 对象时,Dcision 使用 state 的值。其他任何内容——带有其他键的对象、数组、字符串——就是状态本身。这让第三方工具可以原样发送它自己的 payload;但其字段仍必须符合决策的状态 schema。
只有一个 state 字段的 payload
如果你连接的系统发送类似 { "state": "CA" } 的内容——恰好有一个名为 state 的字段且别无其他——Dcision 会将其解包,状态变为 "CA"。请自行包装此类 payload:{ "state": { "state": "CA" } }。
请求体最大为 32 MB,以便状态可以携带文件——每个最大 20 MB,合计 24 MB。不含文件的状态仍须在 128 KB 以内;超出时调用返回 422 INVALID_STATE。
发送文件
要发送照片、语音消息或文档,请以 multipart/form-data 发送 POST 请求——这正是 HTML 表单、n8n、Make 或 Zapier 上传文件时发送的格式。Dcision 根据各个部分构建状态:
| 部分 | 变为 |
|---|---|
| 文本字段 | 状态中同名的字符串字段。 |
| 文件 | 同名字段中的文件:{ "data", "filename", "mime_type" },如输入中所述。请将该字段声明为 image、audio 或 file。 |
名为 state 的字段 | 可选。状态的初始 JSON 对象;其他部分会添加到其中,并替换其中的同名字段。 |
curl https://api.dcision.io/v1/hooks/whk_… \
-F state='{"message":"Can we pay this?"}' \
-F invoice=@invoice.pdf表单字段始终是字符串:状态 schema 中的 number 或 boolean 字段若以表单字段发送,将无法通过校验(422 INVALID_STATE)。请把这类字段放在 state 部分中。表单中留空的文件输入会被忽略。JSON 请求体同样可以携带文件,以 base64 或 https:// URL 的形式——参见输入。
为请求签名
设置了密钥后,每次调用都必须以下列两种方式之一证明自己知道该密钥。
Dcision-Signature(推荐)——与 Dcision 为其自身 webhook 投递签名所用的方案相同:
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_…——密钥本身,以恒定时间进行比较。它对无代码工具更简单,但密钥会随每个请求传输,被截获的请求也可以被重放;能计算签名时请优先使用签名。两种证明任选其一即可:如果你的工具会添加它自己的 Authorization 请求头(它自己的凭据、API 网关 token),有效的 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());不使用密钥
没有密钥的 webhook 会接受对其 URL 的任何调用:URL 本身就是凭据。这对于快速测试或受信任的内部网络没有问题,但任何看到该 URL 的人——在工具的日志中、共享的截图中、浏览器的历史记录中——都可以运行该决策,而每次运行都计入你工作区的费用。
- 在把 URL 放进第三方工具之前添加密钥,并且不要把密钥放在 URL 中。
- 如果 URL 泄露,请在“高级”标签页中轮换它:旧 URL 会立即失效并返回
404。 - 关闭 webhook 后,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
}
}通过 webhook 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 | webhook 设置了密钥,而调用没有有效的证明:既没有 Dcision-Signature 也没有 Authorization、签名格式错误或不正确、时间戳超出 300 秒窗口,或 Bearer 密钥错误。消息会说明是哪一种。 |
| 402 | CREDITS_EXHAUSTED | 套餐包含的用量已用完,且没有剩余额度。 |
| 402 | SPEND_CAP_REACHED | 已达到计费周期的支出上限。 |
| 402 | QUOTA_EXCEEDED | 设有硬上限的套餐所包含的用量已用完。 |
| 404 | NOT_FOUND | 未知 token、已轮换的 URL,或已关闭的 webhook。 |
| 409 | DECISION_NOT_DEPLOYED | 该决策从未部署过。 |
| 409 | DECISION_DISABLED | 该决策的端点已停用。 |
| 413 | PAYLOAD_TOO_LARGE | 请求体超过 32 MB。 |
| 422 | INVALID_STATE | 状态不符合决策的状态 schema 或引擎的 token 预算、不含文件的状态超过 128 KB、某个文件超过 20 MB,或文件超过 10 个。 |
| 429 | RATE_LIMITED | 工作区本分钟的 webhook 速率限制已用完(有独立的窗口,与 API 密钥分开)——或者该 webhook 本分钟收到了超过 30 次签名或密钥错误的调用(Retry-After: 60)。 |
| 424, 5xx | ENGINE_…、INTERNAL_ERROR | 与运行决策中相同。 |
被拒绝的调用——签名错误、无效 JSON、速率限制——不会成为执行记录,但会出现在“高级”标签页的最近调用列表中,因此你可以看到配置错误的工具发送了什么。
谁能看到 URL
没有密钥时,仅凭 URL 就能运行决策——会计费,且目的地真实执行。因此高级标签页只向成员和管理员显示它;查看者可以看到 webhook 存在,但看不到它的 URL。轮换 URL 和管理密钥仅限管理员。当有人离开团队时,请轮换他们能看到的 URL(以及密钥)。
发送测试请求按钮同样以 live 模式运行(目的地会真实触发),并计为一次 webhook 执行。它显示的请求中签名已被遮盖,因此无法被重放。