Webhook trigger

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

Every decision can have a webhook URL: a secret address that runs the decision's active version when something posts to it — a form, a CRM, Zapier, n8n, Make, Pipedream or another backend. It needs no API key, so tools that can only call a URL can trigger a decision, and you can add a secret so that only callers who know it are accepted.

The webhook trigger is inbound: someone calls Dcision. Webhook destinations go the other way — Dcision calls you after it decides — and use the decision.completed event.

Set it upCopy Anchor Link

Open the decision in the app and go to its Advanced tab:

1. Turn the webhook on. Dcision creates the URL: https://api.dcision.io/v1/hooks/whk_ followed by 32 letters and digits. Copy it.
2. Generate a secret (recommended). The full whsec_… value is shown only once — store it where the caller can read it, for example as DCISION_WEBHOOK_SECRET.
3. Send a test from the tab's console: Dcision calls the real URL, signed with the secret, and shows the request and the response. The test runs the decision like any caller and counts as a run.

The tab also lists the latest calls as they arrive, refusals included, and has ready-made cURL, Node.js and Python snippets with your URL. Turning the webhook on or off needs the Member role; rotating the URL and generating, replacing or removing the secret need Admin — see Team and roles.

The URL runs the deployed version: deploy the decision before you point a system at it.

RequestCopy Anchor Link

PathCopy Anchor Link

Query parametersCopy Anchor Link

HeadersCopy Anchor Link

Idempotency-Key isn't supported on webhook URLs: a retried call runs — and is billed — again.

BodyCopy Anchor Link

Send the state wrapped, as for the API, or the payload itself:

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

{ "message": "Can I get a demo next week?", "company_size": 80 }

When the body is a JSON object whose only key is state, Dcision uses the value of state. Anything else — an object with other keys, an array, a string — is the state. That lets a third-party tool post its own payload unchanged; its fields must still match the decision's state schema.

The body must be at most 128 KB.

Sign the requestCopy Anchor Link

With a secret, every call must prove it knows it, in one of two ways.

Dcision-Signature (recommended) — the same scheme Dcision uses to sign its own webhook deliveries:

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

t is the current Unix time in seconds; calls whose t is more than 300 seconds away from Dcision's clock are refused, so a captured request can't be replayed later. Sign the exact bytes you send — serialize the body once and reuse that string.

Authorization: Bearer whsec_… — the secret itself, compared in constant time. It's simpler for no-code tools, but the secret travels with every request and a captured request can be replayed; prefer the signature when you can compute it. Either proof is enough: if your tool adds its own Authorization header (a credential of its own, an API gateway token), a valid Dcision-Signature still passes.

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"

In Zapier, n8n or Make, use an HTTP or webhook step with method POST, the URL, a JSON body and a header Authorization = Bearer whsec_… stored as a credential.

Without a secretCopy Anchor Link

A webhook without a secret accepts any call to its URL: the URL itself is the credential. That's fine for a quick test or a trusted internal network, but anyone who sees the URL — in a tool's logs, a shared screenshot, a browser's history — can run the decision, and every run is billed to your workspace.

• Add a secret before you put the URL in a third-party tool, and keep the secret out of the URL.
• If a URL leaks, rotate it in the Advanced tab: the old URL stops working at once and answers 404.
• Turning the webhook off makes the URL answer 404 NOT_FOUND, the same answer as a URL that never existed.

Removing the secret makes the URL accept unsigned calls again.

ResponseCopy Anchor Link

The same response as POST /v1/decisions/{slug} — result, confidence, scores, composites, action, action_reason, destinations and 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
  }
}

Runs through a webhook URL:

• are billed like API calls and count toward the plan's included volume — past it they use credits, and without credits they answer 402 CREDITS_EXHAUSTED;
• share the workspace's decisions rate limit with the API — see Rate limits;
• run the decision's destinations with livemode: true;
• appear in Executions, in the decision's Overview with the API traffic, and in GET /v1/executions with source: "webhook".

ErrorsCopy Anchor Link

Errors use the standard format, { "error": { "code", "message", "request_id" } }.

Refused calls — a bad signature, invalid JSON, the rate limit — don't become executions, but they appear in the Advanced tab's list of latest calls, so you can see what a misconfigured tool sends.

Who sees the URLCopy Anchor Link

Without a secret, the URL alone runs the decision — billed, with live destinations. So the Advanced tab shows it only to members and admins; viewers see that the webhook exists, but not its URL. Rotating the URL and managing the secret are for admins. When someone leaves the team, rotate the URL (and the secret) they could see.

The Send test request button runs in live mode as well (destinations fire for real) and counts as a webhook execution. The request it shows has the signature masked, so it can't be replayed.