Webhook de entrada

POST /v1/hooks/{token} — ejecuta una decisión desplegada desde una URL secreta sin clave de API, desde formularios, CRM, Zapier, n8n, Make o cualquier backend, con firma opcional mediante un secreto whsec_.

POST https://api.dcision.io/v1/hooks/whk_…

Cada decisión puede tener una URL de webhook: una dirección secreta que ejecuta la versión activa de la decisión cuando algo le hace un POST — un formulario, un CRM, Zapier, n8n, Make, Pipedream u otro backend. No necesita clave de API, así que las herramientas que solo pueden llamar a una URL pueden disparar una decisión, y puedes agregar un secreto para que solo se acepten las llamadas de quienes lo conocen.

El webhook de entrada es entrante: alguien llama a Dcision. Los destinos de webhook van en sentido contrario — Dcision te llama después de decidir — y usan el evento decision.completed.

Configúralo

Abre la decisión en la app y ve a su pestaña Avanzado:

  1. Activa el webhook. Dcision crea la URL: https://api.dcision.io/v1/hooks/whk_ seguido de 32 letras y dígitos. Cópiala.
  2. Genera un secreto (recomendado). El valor completo whsec_… se muestra una sola vez — guárdalo donde quien llama pueda leerlo, por ejemplo como DCISION_WEBHOOK_SECRET.
  3. Envía una prueba desde la consola de la pestaña: Dcision llama a la URL real, firmada con el secreto, y muestra la solicitud y la respuesta. La prueba ejecuta la decisión como cualquier llamador y cuenta como una ejecución.

La pestaña también lista las últimas llamadas a medida que llegan, incluidas las rechazadas, y tiene fragmentos listos de cURL, Node.js y Python con tu URL. Activar o desactivar el webhook requiere el rol Miembro; rotar la URL y generar, reemplazar o quitar el secreto requieren Administrador — consulta Equipo y roles.

La URL ejecuta la versión publicada: despliega la decisión antes de apuntar un sistema hacia ella.

Solicitud

Ruta

ParámetroDescripción
tokenEl token whk_… del webhook de la decisión. Identifica tanto la decisión como el workspace.

Parámetros de consulta

ParámetroDescripción
includeOpcional. probabilities agrega la distribución completa de cada pregunta, como en Ejecutar una decisión.

Headers

HeaderObligatorioDescripción
Content-TypeRecomendadoapplication/json (cualquier otro valor también se lee como JSON), text/plain para enviar un estado de texto tal cual, o multipart/form-data para subir archivos — consulta Enviar archivos.
Dcision-SignatureCon un secretot=<unix seconds>,v1=<hex> — consulta Firmar la solicitud.
AuthorizationCon un secreto, en lugar de la firmaBearer whsec_… — el propio secreto, para herramientas que no pueden calcular un HMAC.

Idempotency-Key no se admite en las URLs de webhook: una llamada reintentada se ejecuta — y se factura — de nuevo.

Body

Envía el estado envuelto, como en la API, o el payload tal cual:

Envuelto
{ "state": { "message": "Can I get a demo next week?", "company_size": 80 } }
Payload sin envolver
{ "message": "Can I get a demo next week?", "company_size": 80 }

Cuando el body es un objeto JSON cuya única clave es state, Dcision usa el valor de state. Cualquier otra cosa — un objeto con otras claves, un array, un string — es el estado. Eso permite que una herramienta de terceros envíe su propio payload sin cambios; sus campos aún deben coincidir con el esquema del estado de la decisión.

Un payload con un único campo state

Si el sistema que conectas envía algo como { "state": "CA" } — un campo que casualmente se llama state y nada más —, Dcision lo desenvuelve y el estado pasa a ser "CA". Envuelve tú mismo esos payloads: { "state": { "state": "CA" } }.

El body debe tener como máximo 32 MB, para que un estado pueda llevar archivos — hasta 20 MB cada uno, 24 MB en total. El estado sin sus archivos debe seguir cabiendo en 128 KB; por encima, la llamada responde 422 INVALID_STATE.

Enviar archivos

Para enviar una foto, una nota de voz o un documento, publica multipart/form-data — lo que envían un formulario HTML, n8n, Make o Zapier cuando suben un archivo. Dcision construye el estado a partir de las partes:

ParteSe convierte en
Un campo de textoUn campo string del estado, con el mismo nombre.
Un archivoUn archivo en el campo del mismo nombre: { "data", "filename", "mime_type" }, como se describe en Entradas. Declara ese campo como image, audio o file.
Un campo llamado stateOpcional. Un objeto JSON del que parte el estado; las demás partes se le añaden y reemplazan sus campos del mismo nombre.
curl https://api.dcision.io/v1/hooks/whk_… \
  -F state='{"message":"Can we pay this?"}' \
  -F invoice=@invoice.pdf

Los campos de formulario siempre son strings: un campo number o boolean del esquema del estado enviado como campo de formulario no pasa la validación (422 INVALID_STATE). Pon esos campos en la parte state. Un campo de archivo que se deja vacío en un formulario se ignora. Un body JSON también puede llevar archivos, en base64 o como URLs https:// — consulta Entradas.

Firmar la solicitud

Con un secreto, cada llamada debe demostrar que lo conoce, de una de estas dos formas.

Dcision-Signature (recomendada) — el mismo esquema que Dcision usa para firmar sus propias entregas de webhook:

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

t es la hora Unix actual en segundos; las llamadas cuyo t se aleja más de 300 segundos del reloj de Dcision se rechazan, para que una solicitud capturada no pueda reproducirse más tarde. Firma los bytes exactos que envías — serializa el body una vez y reutiliza ese string. Para un body multipart/form-data, el HMAC cubre "<t>." seguido de los bytes sin procesar del body, boundaries y archivos incluidos — consulta Firmar un body multipart.

Authorization: Bearer whsec_… — el propio secreto, comparado en tiempo constante. Es más simple para herramientas no-code, pero el secreto viaja con cada solicitud y una solicitud capturada puede reproducirse; prefiere la firma cuando puedas calcularla. Cualquiera de las dos pruebas basta: si tu herramienta agrega su propio header Authorization (una credencial propia, un token de un API gateway), un Dcision-Signature válido sigue pasando.

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"

En Zapier, n8n o Make, usa un paso HTTP o de webhook con el método POST, la URL, un body JSON y un header Authorization = Bearer whsec_… guardado como credencial.

Firmar un body multipart

Construye primero el body multipart, firma sus bytes y luego envía esos mismos bytes con el mismo Content-Type (lleva el boundary). Con curl -F es curl quien construye el body, así que no puedes firmarlo de antemano: usa Authorization: Bearer whsec_… en ese caso, o construye el body en código:

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

Sin secreto

Un webhook sin secreto acepta cualquier llamada a su URL: la propia URL es la credencial. Eso está bien para una prueba rápida o una red interna de confianza, pero cualquiera que vea la URL — en los logs de una herramienta, en una captura de pantalla compartida, en el historial de un navegador — puede ejecutar la decisión, y cada ejecución se factura a tu workspace.

  • Agrega un secreto antes de poner la URL en una herramienta de terceros, y mantén el secreto fuera de la URL.
  • Si una URL se filtra, rótala en la pestaña Avanzado: la URL anterior deja de funcionar de inmediato y responde 404.
  • Desactivar el webhook hace que la URL responda 404 NOT_FOUND, la misma respuesta que una URL que nunca existió.

Quitar el secreto hace que la URL vuelva a aceptar llamadas sin firmar.

Respuesta

La misma respuesta que POST /v1/decisions/{slug} — result, confidence, scores, composites, action, action_reason, destinations y 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
  }
}

Las ejecuciones a través de una URL de webhook:

  • se facturan como las llamadas a la API y cuentan para el volumen incluido del plan — una vez superado, usan créditos, y sin créditos responden 402 CREDITS_EXHAUSTED;
  • comparten el rate limit de decisiones del workspace con la API — consulta Rate limits;
  • ejecutan los destinos de la decisión con livemode: true;
  • aparecen en Ejecuciones, en el Resumen de la decisión junto con el tráfico de la API, y en GET /v1/executions con source: "webhook".

Errores

Los errores usan el formato estándar, { "error": { "code", "message", "request_id" } }.

EstadoCódigoCuándo
400INVALID_REQUESTUn body vacío, un body que no es JSON válido, un body multipart/form-data mal formado, o una parte state que no es un objeto JSON.
401UNAUTHORIZEDEl webhook tiene un secreto y la llamada no tiene una prueba válida: ni Dcision-Signature ni Authorization, una firma mal formada o incorrecta, un timestamp fuera de la ventana de 300 segundos, o un secreto Bearer incorrecto. El mensaje dice cuál.
402CREDITS_EXHAUSTEDEl volumen incluido del plan se agotó y no quedan créditos.
402SPEND_CAP_REACHEDSe alcanzó el límite de gasto del ciclo de facturación.
402QUOTA_EXCEEDEDSe agotó el volumen incluido de un plan con límite estricto.
404NOT_FOUNDToken desconocido, una URL rotada o un webhook desactivado.
409DECISION_NOT_DEPLOYEDLa decisión nunca se ha desplegado.
409DECISION_DISABLEDEl endpoint de la decisión está desactivado.
413PAYLOAD_TOO_LARGEEl body supera los 32 MB.
422INVALID_STATEEl estado no coincide con el esquema del estado de la decisión o con el presupuesto de tokens del motor, el estado sin sus archivos supera los 128 KB, un archivo supera los 20 MB, o hay más de 10 archivos.
429RATE_LIMITEDSe agotó el rate limit de webhooks del workspace para ese minuto (una ventana propia, separada de las claves de API) — o el webhook recibió más de 30 llamadas con una firma o un secreto incorrectos en este minuto (Retry-After: 60).
424, 5xxENGINE_…, INTERNAL_ERRORComo en Ejecutar una decisión.

Las llamadas rechazadas — una firma incorrecta, JSON no válido, el rate limit — no se convierten en ejecuciones, pero aparecen en la lista de últimas llamadas de la pestaña Avanzado, para que puedas ver qué envía una herramienta mal configurada.

Quién ve la URL

Sin secreto, la URL por sí sola ejecuta la decisión — con facturación y con destinos reales. Por eso la pestaña Avanzado solo la muestra a miembros y administradores; los lectores ven que el webhook existe, pero no su URL. Rotar la URL y gestionar el secreto corresponde a los administradores. Cuando alguien deja el equipo, rota la URL (y el secreto) que podía ver.

El botón Enviar solicitud de prueba también se ejecuta en modo real (los destinos se disparan de verdad) y cuenta como una ejecución por webhook. La solicitud que muestra tiene la firma enmascarada, así que no puede reproducirse.

En esta página