Webhook Node

A webhook is a web address that listens for data. When another app, website or script sends data to it, your workflow starts. The caller can get a quick “received” answer, or wait for your workflow’s result. When the result takes longer, the caller gets a link to fetch it later.

Webhook node configuration form — Webhook configuration — CogniAgent generates the address and shows what to send.

When to use

Form submissions — run a workflow when someone fills out a form on your website, Typeform or a survey.
Other apps — let Zapier, Make or any app that can send web requests start your workflow.
Your own software — call your workflow from your website, backend or scripts.
AI answers on demand — send a question and get the workflow’s answer back in the same call.

Get your webhook address

Add and save the node

Add a Webhook node to your workflow and save it.

Copy the address

Open the node and copy the Webhook URL.

Run the workflow

Start your workflow. Calls to a stopped workflow are refused.

The address looks like this:

https://app.cogniagent.ai/api/webhooks/application/<workflow-id>/<webhook-id>

Your workflow must be running for the webhook to accept data. The workspace owner must also have confirmed their email address.

Send data to your webhook

Your webhook accepts any method: GET, POST, PUT, PATCH or DELETE. Send JSON in the body for structured data. Anything else arrives as text.

curl -X POST "https://app.cogniagent.ai/api/webhooks/application/<workflow-id>/<webhook-id>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Maria Lopez", "email": "maria@example.com", "message": "Do you ship to Portugal?"}'

Later steps read the request with {{webhook_1.body.email}}, {{webhook_1.headers.user-agent}} or {{webhook_1.queryParams.source}}. Replace webhook_1 with your node’s key.

Choose what the caller gets back

Pick an option under Response in the node settings.

Acknowledge right away (default)

The caller gets an answer as soon as the call is received. Your workflow keeps running in the background.

{
  "success": true,
  "message": "Webhook processed successfully",
  "applicationId": "<workflow-id>",
  "webhookId": "<webhook-id>",
  "executionMode": "multi_instance",
  "enqueuedExecutions": ["new_execution"],
  "timestamp": "2026-10-09T12:00:00.000Z"
}

Use this for apps that only need to know you received their data, like GitHub, Stripe or form tools.

Return the output of one step

Choose a step that runs after the webhook. The caller gets that step’s output as soon as it finishes, even if later steps are still running.Use this when one step produces the answer, for example an LLM reply, and later steps only log or notify.

If the step fails, the call answers with an error.
If the step does not run for this call, for example because it sits on the other side of a condition, the call answers with an empty result.
If the step runs inside a loop, the call answers once the loop is done, with the step’s most recent output.
If you choose a Human Step, the call answers with the person’s decision.
For a coworker, choose a step on its result branch. The coworker step itself only says the work started.

Return the output of the last steps

The caller gets an answer when everything this call started has finished. The answer holds the output of each last step: a step that ran and was not followed by another step that ran.Steps inside a loop are never last steps, including the branches a Human Step inside the loop starts. The loop is, or the steps that follow it. To return what the loop produced, add a step after it that collects the results. Tools that an LLM step calls are not last steps either; the LLM step is.Use this when the result comes from the end of the workflow, or from several branches.

In this workflow, a call where the order is in stock runs Check stock, Reserve items and Send confirmation. The last step is Send confirmation, so the answer is its output, keyed by its node key.

{
  "success": true,
  "status": "completed",
  "result": {
    "send_confirmation": { "messageId": "msg_7c41", "sent": true }
  }
}

Wait for the result

Wait for the result sets how long the call waits, from 0 to 50 seconds. The default is 25.

The result is ready in time: the caller gets 200 with the result.
The result is not ready: the caller gets 202 Accepted and a result link to fetch it later. The workflow keeps running.
Set 0 to always answer with the result link right away.

{
  "success": true,
  "runId": "whr_cm2x9s0f80000qz6k3n1d7h2a",
  "status": "running",
  "executionId": "<run-id>",
  "resultUrl": "https://app.cogniagent.ai/api/webhooks/application/<workflow-id>/<webhook-id>/runs/whr_cm2x9s0f80000qz6k3n1d7h2a?token=<secret>",
  "pollAfterSeconds": 2
}

The same link is in the Location header. The Retry-After header says how many seconds to wait before you ask again.

Fetch a result later

Send a GET request to the result link. Repeat it until the status is no longer 202.

curl -i "https://app.cogniagent.ai/api/webhooks/application/<workflow-id>/<webhook-id>/runs/<run-id>?token=<secret>"

Status	Meaning
`202`	Still running. Ask again after `Retry-After` seconds.
`200`	Done. The body holds the result.
`204`	Done, and the result is empty. Only when the answer body is Result only.
`424`	The run failed. The body says which steps failed.
`404`	The link is wrong or has expired.

Add &wait=20 to the link to hold each request open for up to 20 seconds (25 at most). You get the result the moment it is ready, with far fewer requests.

Choose the answer body

Answer body sets the shape of a successful answer.

Result with run details
Result only

The default. The result sits under result, next to the run’s details.

{
  "success": true,
  "runId": "whr_cm2x9s0f80000qz6k3n1d7h2a",
  "status": "completed",
  "executionId": "<run-id>",
  "startedAt": "2026-10-09T12:00:00.000Z",
  "finishedAt": "2026-10-09T12:00:03.412Z",
  "result": { "reply": "Yes, we ship to Portugal in 3 to 5 days." }
}

The body is the output itself. A text output is sent as plain text. An empty output answers 204 No Content.

{ "reply": "Yes, we ship to Portugal in 3 to 5 days." }

Use this when the caller expects an exact body, for example a chat widget or another API.

A failed run always answers with run details and status 424 Failed Dependency, whatever the answer body. The workflow failed, not the webhook, so callers and proxies do not mistake it for a temporary outage and retry it:

{
  "success": false,
  "runId": "whr_cm2x9s0f80000qz6k3n1d7h2a",
  "status": "failed",
  "result": null,
  "error": {
    "code": "workflow_failed",
    "message": "The workflow failed before it could answer.",
    "failedNodes": [{ "key": "reserve_items", "name": "Reserve items" }]
  }
}

The answer names the steps that failed, never their error text. Open the run in your workflow’s history to see the details.

Error code	Meaning
`node_failed`	The step chosen to answer failed.
`workflow_failed`	A step failed before the run could answer. A step that fails inside a loop iteration does not count, because the loop moves on.
`trigger_not_executed`	The run did not start, for example because the workspace is out of credits.
`execution_stopped`	Someone stopped the run. `execution_paused` and `execution_cancelled` work the same way.
`result_too_large`	The result is over 5 MB. Read it from the run history.

What counts as finished

A call is finished when nothing it started is still queued or running.

Conditions, branches and merges — every branch the call took counts.
Loops — the call waits for every iteration and for the steps after the loop.
Pause steps — the call waits through the pause. Keep Wait for the result short and fetch the result later.
Human Step — the call waits for the person to answer. Fetch the result later. Result links expire after 24 hours.
Coworkers — a step that waits for a coworker’s result keeps the call open until the result arrives.
Conversations — a Chat & Voice Agent can keep sending events for days, so the call does not wait for it, and the steps its events start are never part of the answer.
Custom events and variable changes — a branch that one of these starts runs on its own and is not part of the call.
Retries — when CogniAgent retries part of a run after a temporary error and the retry succeeds, the call does not fail.
Stop — if someone stops the run, the result link answers with the execution_stopped error.

When the webhook sends data into a workflow that is already running, for example in single-instance mode, the answer belongs to the most recent run. Any other runs that received the data are listed under dispatchedExecutions.

Keep your webhook secure

Anyone who knows your webhook address can send data to it. Turn on authentication for anything that matters.

Turn on Authentication Required and generate an Auth Token. Callers then send it with every request:

curl -X POST "https://app.cogniagent.ai/api/webhooks/application/<workflow-id>/<webhook-id>" \
  -H "Authorization: Bearer <auth-token>" \
  -H "Content-Type: application/json" \
  -d '{"orderId": "SO-2291"}'

Set a Custom HTTP Header Name, such as X-Api-Key, to send the bare token in that header instead. Calls without the right token get 401. Treat result links like passwords:

Each link carries its own secret token. Anyone with the link can read that one result.
Links expire 24 hours after the run’s last activity.
You can send the token in an X-Webhook-Run-Token header instead of the link, to keep it out of logs.

Example: answer a website question with AI

Receive the question

Add a Webhook node. Under Response, choose Return the output of one step.

Write the answer

Connect an LLM node with the prompt:

Answer this customer question in two sentences: {{webhook_1.body.message}}

Pick the answer step

Back in the Webhook node, choose the LLM node as Step to answer with. Set Answer body to Result only.

Log the question

Connect an HTTP Request after the LLM node to save the question to your CRM. The caller already has the answer and does not wait for it.

Example: triage new GitHub issues

GitHub only needs to know you received each event, so keep Acknowledge right away. Point GitHub at your webhook address and select issue events.

Tips

Use query parameters for details that stay the same for a caller, like ?source=website, and the body for the data that changes.

Test with a short curl call before you connect a production system. The run shows up in your workflow’s history with the request it received.

Settings

string

default:"Webhook"

What to call this node on the canvas.

string

default:"webhook_1"

A short code to reference this node’s data, like {{webhook_1.body}}.

string

default:"new_execution"

In multi-instance workflows, whether each call starts a new run or joins a running one. See Execution modes.

boolean

default:"false"

Refuse calls that do not carry the auth token.

string

The token callers send as Authorization: Bearer <token>.

string

Send the bare token in this header instead of Authorization.

string

default:"acknowledge"

What the caller gets back:

acknowledge — answer right away.
node_output — answer with the output of the step in responseNodeId.
last_nodes — answer with the output of the last steps.

string

The step whose output answers the call. Used with node_output.

number

default:"25"

How long the call waits for the result, from 0 to 50 seconds. After that the caller gets a result link.

string

default:"envelope"

envelope — the result with run details.
raw — the result only.

Outputs

object

The data that was sent: JSON fields, or the text itself.

object

The request headers, with lowercase names.

object

Values from the address, like ?userId=123, which gives userId: "123".

HTTP Request

Call other services from your workflow.

If / else

Check incoming data before you act on it.

Loop

Process every item a caller sends.

Execution modes

Decide whether each call starts its own run.

Overview

Triggers

Actions

Logic

Communication

When to use

Get your webhook address

Send data to your webhook

Choose what the caller gets back

Wait for the result

Fetch a result later

Choose the answer body

What counts as finished

Keep your webhook secure

Example: answer a website question with AI

Example: triage new GitHub issues

Tips

Settings

Outputs

HTTP Request

If / else

Loop

Execution modes

​When to use

​Get your webhook address

​Send data to your webhook

​Choose what the caller gets back

​Wait for the result

​Fetch a result later

​Choose the answer body

​What counts as finished

​Keep your webhook secure

​Example: answer a website question with AI

​Example: triage new GitHub issues

​Tips

​Settings

​Outputs

​Related nodes

HTTP Request

If / else

Loop

Execution modes

When to use

Get your webhook address

Send data to your webhook

Choose what the caller gets back

Wait for the result

Fetch a result later

Choose the answer body

What counts as finished

Keep your webhook secure

Example: answer a website question with AI

Example: triage new GitHub issues

Tips

Settings

Outputs

Related nodes