入站 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 事件。

设置

在应用中打开决策,进入其高级标签页:

  1. 开启 webhook。 Dcision 会创建 URL:https://api.dcision.io/v1/hooks/whk_ 加上 32 个字母和数字。复制它。
  2. 生成密钥(推荐)。完整的 whsec_… 值只显示一次——把它保存在调用方可以读取的地方,例如保存为 DCISION_WEBHOOK_SECRET。
  3. 从该标签页的控制台发送测试请求: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 } }
原始 payload
{ "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_…,或在代码中构建请求体:

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());

不使用密钥

没有密钥的 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:

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
  }
}

通过 webhook 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 对象。
401UNAUTHORIZEDwebhook 设置了密钥,而调用没有有效的证明:既没有 Dcision-Signature 也没有 Authorization、签名格式错误或不正确、时间戳超出 300 秒窗口,或 Bearer 密钥错误。消息会说明是哪一种。
402CREDITS_EXHAUSTED套餐包含的用量已用完,且没有剩余额度。
402SPEND_CAP_REACHED已达到计费周期的支出上限。
402QUOTA_EXCEEDED设有硬上限的套餐所包含的用量已用完。
404NOT_FOUND未知 token、已轮换的 URL,或已关闭的 webhook。
409DECISION_NOT_DEPLOYED该决策从未部署过。
409DECISION_DISABLED该决策的端点已停用。
413PAYLOAD_TOO_LARGE请求体超过 32 MB。
422INVALID_STATE状态不符合决策的状态 schema 或引擎的 token 预算、不含文件的状态超过 128 KB、某个文件超过 20 MB,或文件超过 10 个。
429RATE_LIMITED工作区本分钟的 webhook 速率限制已用完(有独立的窗口,与 API 密钥分开)——或者该 webhook 本分钟收到了超过 30 次签名或密钥错误的调用(Retry-After: 60)。
424, 5xxENGINE_…、INTERNAL_ERROR与运行决策中相同。

被拒绝的调用——签名错误、无效 JSON、速率限制——不会成为执行记录,但会出现在“高级”标签页的最近调用列表中,因此你可以看到配置错误的工具发送了什么。

谁能看到 URL

没有密钥时,仅凭 URL 就能运行决策——会计费,且目的地真实执行。因此高级标签页只向成员和管理员显示它;查看者可以看到 webhook 存在,但看不到它的 URL。轮换 URL 和管理密钥仅限管理员。当有人离开团队时,请轮换他们能看到的 URL(以及密钥)。

发送测试请求按钮同样以 live 模式运行(目的地会真实触发),并计为一次 webhook 执行。它显示的请求中签名已被遮盖,因此无法被重放。

本页内容