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:
- Activa el webhook. Dcision crea la URL:
https://api.dcision.io/v1/hooks/whk_seguido de 32 letras y dígitos. Cópiala. - Genera un secreto (recomendado). El valor completo
whsec_…se muestra una sola vez — guárdalo donde quien llama pueda leerlo, por ejemplo comoDCISION_WEBHOOK_SECRET. - 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ámetro | Descripción |
|---|---|
token | El token whk_… del webhook de la decisión. Identifica tanto la decisión como el workspace. |
Parámetros de consulta
| Parámetro | Descripción |
|---|---|
include | Opcional. probabilities agrega la distribución completa de cada pregunta, como en Ejecutar una decisión. |
Headers
| Header | Obligatorio | Descripción |
|---|---|---|
Content-Type | Recomendado | application/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-Signature | Con un secreto | t=<unix seconds>,v1=<hex> — consulta Firmar la solicitud. |
Authorization | Con un secreto, en lugar de la firma | Bearer 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:
{ "state": { "message": "Can I get a demo next week?", "company_size": 80 } }{ "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:
| Parte | Se convierte en |
|---|---|
| Un campo de texto | Un campo string del estado, con el mismo nombre. |
| Un archivo | Un 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 state | Opcional. 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.pdfLos 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:
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:
{
"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/executionsconsource: "webhook".
Errores
Los errores usan el formato estándar, { "error": { "code", "message", "request_id" } }.
| Estado | Código | Cuándo |
|---|---|---|
| 400 | INVALID_REQUEST | Un 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. |
| 401 | UNAUTHORIZED | El 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. |
| 402 | CREDITS_EXHAUSTED | El volumen incluido del plan se agotó y no quedan créditos. |
| 402 | SPEND_CAP_REACHED | Se alcanzó el límite de gasto del ciclo de facturación. |
| 402 | QUOTA_EXCEEDED | Se agotó el volumen incluido de un plan con límite estricto. |
| 404 | NOT_FOUND | Token desconocido, una URL rotada o un webhook desactivado. |
| 409 | DECISION_NOT_DEPLOYED | La decisión nunca se ha desplegado. |
| 409 | DECISION_DISABLED | El endpoint de la decisión está desactivado. |
| 413 | PAYLOAD_TOO_LARGE | El body supera los 32 MB. |
| 422 | INVALID_STATE | El 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. |
| 429 | RATE_LIMITED | Se 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, 5xx | ENGINE_…, INTERNAL_ERROR | Como 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.
API de sesiones embebidas
POST /v1/embed/sessions — abre el editor embebible para uno de tus usuarios finales en su sub-workspace; revoca sesiones. Solo desde el servidor.
Eventos de webhook
El evento decision.completed del documento OpenAPI, con la solicitud enviada a los destinos webhook, sus headers, cada campo del evento y las respuestas que Dcision espera.