> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cogniagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Node

> Run your workflow when another app or website sends you data

A webhook is like a special web address that listens for incoming data. When someone (or something) sends data to this address, your workflow starts.

Think of it like a mailbox: other apps and websites can "drop off" information, and your workflow automatically processes it.

<Frame caption="Webhook configuration — CogniAgent generates the URL and shows the expected payload shape.">
  <img src="https://mintcdn.com/glorium/eqWkhSfBUec9afZU/images/nodes/node-webhook-form.png?fit=max&auto=format&n=eqWkhSfBUec9afZU&q=85&s=6c152704041e04fe543e3fbec4911668" alt="Webhook node configuration form" width="1440" height="1200" data-path="images/nodes/node-webhook-form.png" />
</Frame>

## When to Use

* **Form submissions** - When someone fills out a form on your website, Typeform, or survey
* **Connecting other apps** - When apps like Zapier or Make need to trigger your workflow
* **Your own software** - When your website or app needs to kick off a workflow
* **Automation platforms** - When you want to connect tools that aren't directly integrated

## Getting Your Webhook Address

After adding a Webhook node:

1. Save your workflow
2. Click the Webhook node to see its settings
3. Copy the web address from the **Webhook URL** field

This is the address other apps will send data to. It looks something like:

```
https://app.cogniagent.ai/webhooks/your-workspace/your-app/webhook_1
```

<Warning>
  Your workflow must be **running** for the webhook to work. If your workflow is stopped, the webhook won't accept any data.
</Warning>

## Example: Form Submission Handler

Process contact form submissions and send them to your team:

<Steps>
  <Step title="Create the webhook trigger">
    Add a Webhook node configured for POST requests.
  </Step>

  <Step title="Process the submission">
    Connect to an Ask AI node that categorizes the inquiry:

    ```
    Categorize this contact form submission into one of:
    Sales, Support, Partnership, Other

    Name: {{webhook_1.body.name}}
    Email: {{webhook_1.body.email}}
    Message: {{webhook_1.body.message}}
    ```
  </Step>

  <Step title="Route to the right team">
    Use a Multi-Condition node to route based on the AI's categorization, sending notifications to different Slack channels.
  </Step>
</Steps>

### Expected Request Body

```json theme={null}
{
  "name": "Jane Smith",
  "email": "jane@example.com",
  "message": "I'm interested in your enterprise plan...",
  "source": "website"
}
```

### Calling the Webhook

```bash theme={null}
curl -X POST https://app.cogniagent.ai/webhooks/ws_123/app_456/webhook_1 \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Smith", "email": "jane@example.com", "message": "Hello!"}'
```

## Example: GitHub Integration

Trigger a workflow when new issues are created:

```
Workflow: GitHub Issue Triage
├── Webhook (receives GitHub webhook payload)
├── Condition (check if action is "opened")
├── Ask AI (analyze issue and suggest labels)
└── HTTP Request (add labels via GitHub API)
```

Configure GitHub to send webhooks to your endpoint for issue events.

## Response Modes

### Immediate Response

Returns immediately with a confirmation:

```json theme={null}
{
  "success": true,
  "executionId": "exec_abc123"
}
```

Use this when the caller doesn't need to wait for results.

### Last Node Response

Waits for the workflow to complete and returns the output of the final node. Use this when:

* The caller needs the processed result
* Building synchronous API integrations
* Forms that should display a confirmation message

<Note>
  Last node response mode has a timeout. For long-running workflows, use immediate mode and provide a callback webhook or polling endpoint.
</Note>

## Keeping Your Webhook Secure

<Warning>
  Anyone who knows your webhook URL can send data to it. Implement validation for production workflows.
</Warning>

* **Validate incoming data** - Check that requests contain expected fields before processing
* **Use a webhook secret** - Include a secret token in requests and verify it in your workflow
* **Rate limiting** - CogniAgent includes built-in rate limiting to prevent abuse

### Using a Webhook Secret

Require a secret token to verify requests are legitimate:

```
# In a Condition node, verify the secret:
{{webhook_1.headers.x-webhook-secret}} equals "{{secrets.WEBHOOK_SECRET}}"
```

Only continue the workflow if the secret matches. Store your secret in workspace secrets, not in the workflow.

## Tips

<Tip>
  Use query parameters for metadata that doesn't change per request, and the body for variable data. Example: `?source=website&version=2`
</Tip>

<Tip>
  Test webhooks locally using tools like [ngrok](https://ngrok.com) or [webhook.site](https://webhook.site) before connecting production systems.
</Tip>

## Settings

<ParamField path="name" type="string" default="Webhook">
  What to call this node (shown on the canvas).
</ParamField>

<ParamField path="key" type="string" default="webhook_1">
  A short code to reference this node's data.
</ParamField>

<ParamField path="httpMethod" type="string" default="POST">
  How data is sent to you. Usually POST (the default) works fine.
</ParamField>

<ParamField path="responseMode" type="string" default="immediate">
  What to send back to whoever triggered the webhook:

  * **immediate** - Say "got it!" right away
  * **lastNode** - Wait for the workflow to finish, then send back the result
</ParamField>

## Outputs

<ParamField path="body" type="object">
  The main data that was sent (form fields, JSON data, etc.).
</ParamField>

<ParamField path="headers" type="object">
  Extra information that came with the request (usually not needed).
</ParamField>

<ParamField path="queryParams" type="object">
  Values from the web address (like `?userId=123` gives you `userId: "123"`).
</ParamField>

<ParamField path="method" type="string">
  How the data was sent (GET, POST, etc.).
</ParamField>

## Related Nodes

<CardGroup cols={2}>
  <Card title="HTTP Request" icon="globe" href="/nodes/actions/http-request">
    Make outgoing HTTP requests to other services.
  </Card>

  <Card title="Condition" icon="code-branch" href="/nodes/logic/condition">
    Validate webhook data before processing.
  </Card>
</CardGroup>