Вебхуки

Получайте подписанное событие decision.completed на свой URL — конверт, его заголовки, проверка Dcision-Signature с SDK и без них, сырые тела в Express и Next.js, ротация и дедупликация.

Назначение webhook отправляет POST-запросом итог решения на ваш URL в виде подписанного события decision.completed — в фоне и с повторами. Используйте его, чтобы уведомлять свой бэкенд: обновить запись, поставить задачу в очередь, запустить собственную маршрутизацию.

Настройка

{
  "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 — это URL https:// длиной до 2 048 символов (переменные кодируются для URL) или {{secrets.NAME}}, содержащий весь URL. Тело — всегда событие ниже: чтобы отправить собственное тело — сообщение в Slack, payload для CRM, — используйте 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; livemode равен false для запусков с тестовым ключом (dcs_test_…) и из Playground.
  • data несёт ответы, действие и его причину, а также params — но никогда сам state: сопоставьте нужные получателю поля как параметры.

Каждое поле описано в разделе События вебхуков — справочнике API по этому событию.

Заголовки

ЗаголовокЗначение
User-AgentDcision-Destinations/1.0 (+https://docs.dcision.io/destinations)
Content-Typeapplication/json
Dcision-DeliveryID доставки, 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. Вычислите HMAC-SHA256 от <t>.<raw body> с секретом подписи в виде hex и сравните его с каждым 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 часов удалите старый секрет.

Ответ и дедупликация

  • Отвечайте 2xx в течение 10 секунд, а работу выполняйте асинхронно. Медленные ответы считаются тайм-аутами и повторяются.
  • Доставки — как минимум один раз: тайм-аут или потерянный ответ означают, что событие может прийти снова. Дедуплицируйте по id (или Dcision-Delivery).
  • Каждый ответ не-2xx учитывается: 408, 425, 429 и 5xx повторяются — шесть попыток примерно за семь часов; остальные ответы 4xx и редиректы окончательны. См. Доставка и повторы.
  • Проверяйте livemode, чтобы не пускать тестовые события и события из Playground в продакшен-системы.

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