Webhook de entrada
POST /v1/hooks/{token} — rode uma decisão publicada a partir de uma URL secreta, sem API key, de formulários, CRMs, Zapier, n8n, Make ou qualquer backend, opcionalmente assinada com um segredo whsec_.
POST https://api.dcision.io/v1/hooks/whk_…Toda decisão pode ter uma URL de webhook: um endereço secreto que roda a versão ativa da decisão quando algo faz um POST para ele — um formulário, um CRM, Zapier, n8n, Make, Pipedream ou outro backend. Ele não precisa de API key, então ferramentas que só sabem chamar uma URL podem disparar uma decisão, e você pode adicionar um segredo para que só sejam aceitos os chamadores que o conhecem.
O webhook de entrada é inbound: alguém chama a Dcision. Os destinos webhook vão no sentido contrário — a Dcision chama você depois de decidir — e usam o evento decision.completed.
Configure
Abra a decisão no app e vá até a aba Avançado dela:
- Ligue o webhook. A Dcision cria a URL:
https://api.dcision.io/v1/hooks/whk_seguido de 32 letras e dígitos. Copie-a. - Gere um segredo (recomendado). O valor
whsec_…completo aparece só uma vez — guarde-o onde o chamador consiga lê-lo, por exemplo comoDCISION_WEBHOOK_SECRET. - Envie um teste pelo console da aba: a Dcision chama a URL real, assinada com o segredo, e mostra a requisição e a resposta. O teste roda a decisão como qualquer chamador e conta como uma execução.
A aba também lista as chamadas mais recentes conforme chegam, inclusive as recusadas, e tem trechos prontos de cURL, Node.js e Python com a sua URL. Ligar ou desligar o webhook exige o papel de Membro; trocar a URL e gerar, substituir ou remover o segredo exigem Admin — veja Time e papéis.
A URL roda a versão publicada: publique a decisão antes de apontar um sistema para ela.
Requisição
Caminho
| Parâmetro | Descrição |
|---|---|
token | O token whk_… do webhook da decisão. Ele identifica tanto a decisão quanto o workspace. |
Parâmetros de query
| Parâmetro | Descrição |
|---|---|
include | Opcional. probabilities acrescenta a distribuição completa de cada pergunta, como em Executar uma decisão. |
Headers
| Header | Obrigatório | Descrição |
|---|---|---|
Content-Type | Recomendado | application/json (qualquer outro valor também é lido como JSON), text/plain para enviar um estado de texto como está, ou multipart/form-data para enviar arquivos — veja Envie arquivos. |
Dcision-Signature | Com segredo | t=<unix seconds>,v1=<hex> — veja Assine a requisição. |
Authorization | Com segredo, em vez da assinatura | Bearer whsec_… — o próprio segredo, para ferramentas que não conseguem calcular um HMAC. |
Idempotency-Key não é suportado em URLs de webhook: uma chamada repetida roda — e é cobrada — de novo.
Body
Envie o estado encapsulado, como na API, ou o próprio payload:
{ "state": { "message": "Can I get a demo next week?", "company_size": 80 } }{ "message": "Can I get a demo next week?", "company_size": 80 }Quando o body é um objeto JSON cuja única chave é state, a Dcision usa o valor de state. Qualquer outra coisa — um objeto com outras chaves, um array, uma string — é o estado. Isso permite que uma ferramenta de terceiros poste o próprio payload sem alterações; os campos dele ainda precisam bater com o state schema da decisão.
Um payload com um único campo state
Se o sistema que você conecta envia algo como { "state": "CA" } — um campo que por acaso se chama state e nada mais —, a Dcision o desencapsula e o estado vira "CA". Encapsule esses payloads você mesmo: { "state": { "state": "CA" } }.
O body pode ter no máximo 32 MB, para que um estado possa levar arquivos — até 20 MB cada, 24 MB no total. O estado sem os arquivos ainda precisa caber em 128 KB; acima disso a chamada responde 422 INVALID_STATE.
Envie arquivos
Para enviar uma foto, um áudio ou um documento, poste multipart/form-data — o que um formulário HTML, o n8n, o Make ou o Zapier enviam quando fazem upload de um arquivo. A Dcision monta o estado a partir das partes:
| Parte | Vira |
|---|---|
| Um campo de texto | Um campo string do estado, com o mesmo nome. |
| Um arquivo | Um arquivo no campo de mesmo nome: { "data", "filename", "mime_type" }, como descrito em Entradas. Declare esse campo como image, audio ou file. |
Um campo chamado state | Opcional. Um objeto JSON de onde o estado parte; as outras partes são acrescentadas a ele e substituem os campos de mesmo nome. |
curl https://api.dcision.io/v1/hooks/whk_… \
-F state='{"message":"Can we pay this?"}' \
-F invoice=@invoice.pdfCampos de formulário são sempre strings: um campo number ou boolean do state schema enviado como campo de formulário falha na validação (422 INVALID_STATE). Coloque esses campos na parte state. Um campo de arquivo deixado vazio num formulário é ignorado. Um body JSON também pode levar arquivos, em base64 ou como URLs https:// — veja Entradas.
Assine a requisição
Com um segredo, toda chamada precisa provar que o conhece, de uma de duas formas.
Dcision-Signature (recomendado) — o mesmo esquema que a Dcision usa para assinar as próprias 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 é o horário Unix atual em segundos; chamadas cujo t esteja a mais de 300 segundos do relógio da Dcision são recusadas, para que uma requisição capturada não possa ser repetida depois. Assine os bytes exatos que você envia — serialize o body uma vez e reutilize essa string. Para um body multipart/form-data, o HMAC cobre "<t>." seguido dos bytes brutos do body, boundaries e arquivos incluídos — veja Assine um body multipart.
Authorization: Bearer whsec_… — o próprio segredo, comparado em tempo constante. É mais simples para ferramentas no-code, mas o segredo viaja em toda requisição e uma requisição capturada pode ser repetida; prefira a assinatura quando conseguir calculá-la. Qualquer uma das provas basta: se a sua ferramenta acrescenta o próprio header Authorization (uma credencial dela, um token de API gateway), uma Dcision-Signature válida continua passando.
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"No Zapier, no n8n ou no Make, use um passo HTTP ou de webhook com o método POST, a URL, um body JSON e um header Authorization = Bearer whsec_… guardado como credencial.
Assine um body multipart
Monte primeiro o body multipart, assine os bytes dele e então envie esses mesmos bytes com o mesmo Content-Type (ele carrega o boundary). Com curl -F quem monta o body é o curl, então não dá para assiná-lo antes: use Authorization: Bearer whsec_… nesse caso, ou monte o body em 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());Sem segredo
Um webhook sem segredo aceita qualquer chamada à URL dele: a própria URL é a credencial. Isso serve para um teste rápido ou uma rede interna confiável, mas qualquer pessoa que veja a URL — nos logs de uma ferramenta, num print compartilhado, no histórico de um navegador — pode rodar a decisão, e toda execução é cobrada do seu workspace.
- Adicione um segredo antes de colocar a URL numa ferramenta de terceiros, e mantenha o segredo fora da URL.
- Se uma URL vazar, troque-a na aba Avançado: a URL antiga para de funcionar na hora e responde
404. - Desligar o webhook faz a URL responder
404 NOT_FOUND, a mesma resposta de uma URL que nunca existiu.
Remover o segredo faz a URL voltar a aceitar chamadas sem assinatura.
Resposta
A mesma resposta de POST /v1/decisions/{slug} — result, confidence, scores, composites, action, action_reason, destinations e 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
}
}As execuções por uma URL de webhook:
- são cobradas como chamadas à API e contam para o volume incluído no plano — além dele, usam créditos, e sem créditos respondem
402 CREDITS_EXHAUSTED; - compartilham o rate limit de decisões do workspace com a API — veja Rate limits;
- rodam os destinos da decisão com
livemode: true; - aparecem em Execuções, na Visão geral da decisão junto com o tráfego da API, e em
GET /v1/executionscomsource: "webhook".
Erros
Os erros usam o formato padrão, { "error": { "code", "message", "request_id" } }.
| Status | Código | Quando |
|---|---|---|
| 400 | INVALID_REQUEST | Um body vazio, um body que não é JSON válido, um body multipart/form-data malformado, ou uma parte state que não é um objeto JSON. |
| 401 | UNAUTHORIZED | O webhook tem um segredo e a chamada não tem uma prova válida: nem Dcision-Signature nem Authorization, uma assinatura malformada ou errada, um timestamp fora da janela de 300 segundos, ou um segredo Bearer errado. A mensagem diz qual. |
| 402 | CREDITS_EXHAUSTED | O volume incluído no plano acabou e não há mais créditos. |
| 402 | SPEND_CAP_REACHED | O teto de gasto do ciclo de cobrança foi atingido. |
| 402 | QUOTA_EXCEEDED | O volume incluído de um plano com limite rígido acabou. |
| 404 | NOT_FOUND | Token desconhecido, uma URL trocada ou um webhook desligado. |
| 409 | DECISION_NOT_DEPLOYED | A decisão nunca foi publicada. |
| 409 | DECISION_DISABLED | O endpoint da decisão está desativado. |
| 413 | PAYLOAD_TOO_LARGE | O body é maior que 32 MB. |
| 422 | INVALID_STATE | O estado não bate com o state schema da decisão ou com o orçamento de tokens do engine, o estado sem os arquivos passa de 128 KB, um arquivo passa de 20 MB, ou há mais de 10 arquivos. |
| 429 | RATE_LIMITED | O rate limit de webhook do workspace para o minuto acabou (uma janela própria, separada das API keys) — ou o webhook recebeu mais de 30 chamadas com assinatura ou segredo errados neste minuto (Retry-After: 60). |
| 424, 5xx | ENGINE_…, INTERNAL_ERROR | Como em Executar uma decisão. |
As chamadas recusadas — uma assinatura inválida, um JSON inválido, o rate limit — não viram execuções, mas aparecem na lista de chamadas recentes da aba Avançado, para você ver o que uma ferramenta mal configurada envia.
Quem vê a URL
Sem segredo, a URL sozinha roda a decisão — com cobrança e com destinos reais. Por isso a aba Avançado só a mostra a membros e admins; os leitores veem que o webhook existe, mas não a URL dele. Trocar a URL e gerenciar o segredo cabe aos admins. Quando alguém sai do time, troque a URL (e o segredo) que essa pessoa podia ver.
O botão Enviar requisição de teste também roda em modo live (os destinos disparam de verdade) e conta como uma execução de webhook. A requisição que ele mostra tem a assinatura mascarada, então não pode ser repetida.
API de sessões de embed
POST /v1/embed/sessions — abra o editor incorporável para um dos seus usuários finais no sub-workspace dele; revogue sessões. Só no servidor.
Eventos de webhook
O evento decision.completed do documento OpenAPI — a requisição enviada aos destinos de webhook, os headers, cada campo do evento e as respostas que a Dcision espera.