Webhook

在你的 URL 接收签名的 decision.completed 事件——事件封装、请求头、使用或不使用 SDK 验证 Dcision-Signature、Express 和 Next.js 中的原始请求体、轮换与去重。

webhook 目的地会在后台把决策的结果以签名的 decision.completed 事件 POST 到你的 URL,并带有重试。用它来通知你的后端:更新一条记录、排队一个任务、启动你自己的路由。

配置

{
  "key": "notify_sales",
  "type": "webhook",
  "when": { "conditions": [{ "field": "route", "on": "output", "operator": "eq", "value": "sales" }] },
  "params": {
    "message": { "from": "state.message" },
    "team": { "value": "inbound" }
  },
  "webhook": { "url": "https://example.com/hooks/dcision" }
}

webhook.url 是最多 2,048 个字符的 https:// URL——其中的变量会进行 URL 编码——或者是保存完整 URL 的 {{secrets.NAME}}。请求体始终是下面的事件:如果要发送你自己的请求体——Slack 消息、CRM payload——请使用 API 请求。

事件

POST 请求体
{
  "id": "dlv_8kJx2mQp4LzN7vR1tY6w",
  "type": "decision.completed",
  "created": 1759658400,
  "livemode": true,
  "destination": "notify_sales",
  "data": {
    "decision": "lead-qualification",
    "decision_id": "dec_3fKq9ZtW1mXcV7bN2pLa",
    "version": 4,
    "execution_id": "exec_8HsT2kQw9ZyR4vMn1cXe",
    "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" },
    "params": { "message": "We need pricing for 500 users and want to start next month.", "team": "inbound" }
  }
}
  • id 是投递 ID:此次投递的每次尝试都相同。请据此去重。
  • created 是决策运行的时间,以 Unix 秒表示;对于使用 test 密钥(dcs_test_…)和来自 Playground 的运行,livemode 为 false。
  • data 携带回答、行动及其原因,以及 params——从不包含状态本身:请把接收方需要的字段映射为参数。

每个字段都在该事件的 API 参考 Webhook 事件中有说明。

请求头

请求头值
User-AgentDcision-Destinations/1.0 (+https://docs.dcision.io/destinations)
Content-Typeapplication/json
Dcision-Delivery投递 ID,dlv_…——每次尝试都相同。
Dcision-Attempt尝试次数,1 到 6。
Dcision-Eventdecision.completed
Dcision-Signaturet=<unix seconds>,v1=<hex>——见下文。

验证签名

每次投递都会用你工作区的签名密钥签名——whsec_ 加上 32 个字母和数字。管理员和所有者可以在设置 → 目的地 → 签名密钥中查看它;把它保存在你的服务器上,例如保存为 DCISION_WEBHOOK_SECRET。

Dcision-Signature: t=1759658400,v1=662b905d30dbc7ccce5864c0e9dda66451117e8d3361c3e39bb9f91417199b52

signed_payload = "<t>." + <the raw request body>
v1             = hex( HMAC-SHA256( signing secret, signed_payload ) )

接受一个请求的步骤:

  1. 读取原始请求体——即收到的确切字节。经过解析再序列化的请求体字节不同,永远无法通过验证。
  2. 以 , 拆分请求头,得到 t= 和一个或多个 v1= 条目。
  3. 用签名密钥计算 <t>.<raw body> 的 HMAC-SHA256(十六进制),并以恒定时间与每个 v1 进行比较。任意一个匹配即接受。
  4. 拒绝与你的时钟相差超过 300 秒的时间戳——这是防范重放请求的保护措施。t 是本次尝试的时间:每次重试都会重新签名。

验证失败时返回 400。SDK 一次调用即可完成以上所有步骤。

Express

import express from "express";
import { DcisionError, verifyWebhook } from "@dcision/sdk";

const app = express();

// express.raw, not express.json: the signature covers the exact bytes Dcision sent.
app.post("/hooks/dcision", express.raw({ type: "application/json" }), async (req, res) => {
  let event;
  try {
    event = await verifyWebhook(req.body, req.header("dcision-signature"), process.env.DCISION_WEBHOOK_SECRET!);
  } catch (error) {
    // A bad signature is final (400). Anything else is on our side: 500, so Dcision retries.
    return res.sendStatus(error instanceof DcisionError ? 400 : 500);
  }
  if (await deliveries.seen(event.id)) return res.sendStatus(200);
  await jobs.enqueue("dcision-decision", event.data);
  res.sendStatus(200);
});

Next.js 路由处理程序

app/api/hooks/dcision/route.ts
import { DcisionError, verifyWebhook, type WebhookEvent } from "@dcision/sdk";

export async function POST(request: Request) {
  const body = await request.text(); // the raw body — not request.json()
  let event: WebhookEvent;
  try {
    event = await verifyWebhook(body, request.headers.get("dcision-signature"), process.env.DCISION_WEBHOOK_SECRET!);
  } catch (error) {
    return new Response(null, { status: error instanceof DcisionError ? 400 : 500 });
  }
  await handleDecision(event.data); // throws → 500 → Dcision retries
  return new Response(null, { status: 204 });
}

它可以在 Node.js 和 Edge 运行时上运行。

Python

import os

from flask import Flask, request

from dcision import DcisionError, verify_webhook

app = Flask(__name__)


@app.post("/hooks/dcision")
def dcision_webhook():
    try:
        # get_data(): the raw bytes. Don't read request.json first.
        event = verify_webhook(request.get_data(), request.headers.get("Dcision-Signature"), os.environ["DCISION_WEBHOOK_SECRET"])
    except DcisionError as error:
        return error.message, 400
    if deliveries.seen(event["id"]):
        return "", 200
    handle_decision(event["data"])
    return "", 200

对于缺失或格式错误的请求头、不匹配的签名、超出容差的时间戳或不是事件的请求体,SDK 会抛出 INVALID_SIGNATURE;对于误用——没有密钥,或请求体已被解析——则抛出 TypeError。参见 TypeScript SDK 和 Python SDK。在 SDK 发布之前,需要从源码构建。

不使用 SDK 进行验证

import { createHmac, timingSafeEqual } from "node:crypto";

/** Verifies Dcision-Signature over the raw request body (a string or a Buffer). */
export function verifyDcisionSignature(rawBody, header, secret, toleranceSec = 300) {
  let timestamp;
  const signatures = [];
  for (const part of (header ?? "").split(",")) {
    const [name, value = ""] = part.trim().split("=");
    if (name === "t") timestamp = value;
    else if (name === "v1" && /^[0-9a-f]{64}$/i.test(value)) signatures.push(Buffer.from(value, "hex"));
  }
  if (!timestamp || !/^\d+$/.test(timestamp) || signatures.length === 0) return false;
  const expected = createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest();
  if (!signatures.some((signature) => timingSafeEqual(signature, expected))) return false;
  return Math.abs(Date.now() / 1000 - Number(timestamp)) <= toleranceSec;
}

测试向量

用这个签名检查你的实现——SDK 也是用它测试的。请求体恰好是一行,UTF-8 编码,末尾没有换行符:

输入
secret  whsec_9vX2kLmQ4pRt7wYz1aBc3dEf5gHj8KnS
t       1759658400
原始请求体
{"id":"dlv_8kJx2mQp4LzN7vR1tY6w","type":"decision.completed","created":1759658400,"livemode":true,"destination":"notify_sales","data":{"decision":"lead-qualification","decision_id":"dec_4Qm9Tz2Lx7Wv1Rb8Nc3K","version":3,"execution_id":"exec_8HsT2kQw9ZyR4vMn1cXe","result":{"route":"sales"},"confidence":{"route":0.91},"scores":{},"composites":{},"action":"continue","action_reason":{"type":"default"},"params":{"message":"Olá! Preciso de preço para 500 licenças — urgente 🚀","team":"inbound"}}}
预期结果
v1      662b905d30dbc7ccce5864c0e9dda66451117e8d3361c3e39bb9f91417199b52

测试时间戳检查时,请把时钟设为 1759658400——或使用很大的容差。

轮换签名密钥

在设置 → 目的地中点击轮换会立即创建一个新密钥。在接下来的 24 小时内,Dcision 会用两个密钥为每次投递签名,因此请求头会带有两个 v1= 条目——t=…,v1=<new>,v1=<old>——知道其中任意一个密钥的接收方都能继续验证:

  1. 轮换,并复制新密钥。
  2. 用两个密钥部署你的接收方——SDK 接受一个列表:verifyWebhook(body, header, [newSecret, oldSecret])。
  3. 在 24 小时内移除旧密钥。

响应与去重

  • 在 10 秒内返回 2xx,然后异步处理工作。响应过慢会被视为超时并重试。
  • 投递至少一次:超时或响应丢失意味着事件可能再次到达。请根据 id(或 Dcision-Delivery)去重。
  • 每个非 2xx 响应都会被计入:408、425、429 和 5xx 会被重试——在大约七小时内尝试六次;其他 4xx 响应和重定向是最终结果。参见投递与重试。
  • 检查 livemode,让测试和 Playground 事件远离生产系统。

本页内容