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:

  1. Ligue o webhook. A Dcision cria a URL: https://api.dcision.io/v1/hooks/whk_ seguido de 32 letras e dígitos. Copie-a.
  2. Gere um segredo (recomendado). O valor whsec_… completo aparece só uma vez — guarde-o onde o chamador consiga lê-lo, por exemplo como DCISION_WEBHOOK_SECRET.
  3. 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âmetroDescrição
tokenO token whk_… do webhook da decisão. Ele identifica tanto a decisão quanto o workspace.

Parâmetros de query

ParâmetroDescrição
includeOpcional. probabilities acrescenta a distribuição completa de cada pergunta, como em Executar uma decisão.

Headers

HeaderObrigatórioDescrição
Content-TypeRecomendadoapplication/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-SignatureCom segredot=<unix seconds>,v1=<hex> — veja Assine a requisição.
AuthorizationCom segredo, em vez da assinaturaBearer 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:

Encapsulado
{ "state": { "message": "Can I get a demo next week?", "company_size": 80 } }
Payload bruto
{ "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:

ParteVira
Um campo de textoUm campo string do estado, com o mesmo nome.
Um arquivoUm 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 stateOpcional. 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.pdf

Campos 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:

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

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:

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
  }
}

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/executions com source: "webhook".

Erros

Os erros usam o formato padrão, { "error": { "code", "message", "request_id" } }.

StatusCódigoQuando
400INVALID_REQUESTUm 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.
401UNAUTHORIZEDO 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.
402CREDITS_EXHAUSTEDO volume incluído no plano acabou e não há mais créditos.
402SPEND_CAP_REACHEDO teto de gasto do ciclo de cobrança foi atingido.
402QUOTA_EXCEEDEDO volume incluído de um plano com limite rígido acabou.
404NOT_FOUNDToken desconhecido, uma URL trocada ou um webhook desligado.
409DECISION_NOT_DEPLOYEDA decisão nunca foi publicada.
409DECISION_DISABLEDO endpoint da decisão está desativado.
413PAYLOAD_TOO_LARGEO body é maior que 32 MB.
422INVALID_STATEO 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.
429RATE_LIMITEDO 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, 5xxENGINE_…, INTERNAL_ERRORComo 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.

Nesta página