Universal Webhook

A flexible webhook channel that connects an agent to any external system that can send or receive HTTP requests. Supports all three route types, multiple authentication methods, and configurable outbound payload formatting.

• Supported agents: Agentic Flow

• Route types: Trigger, Conversation, Notification

• Auth: API Key, Basic Auth, Bearer Token, HMAC Signature, or Public

Route Overview

Route	Direction	Use when
Trigger	Inbound only	External system fires the agent with a POST to the Neo webhook URL
Conversation	Bidirectional	External system sends messages to the agent and receives replies at a configured target URL
Notification	Outbound only	Agent sends proactive notifications to a target URL

Before You Start

No external account setup is required. Neo generates the webhook URL after channel creation. Configure the calling system to POST to that URL using the authentication method you define.

Your agent must be published with an active version. For Conversation and Notification routes, the Channel Gateway MCP must be enabled:

• Global: Admin Panel → MCP Servers → Channel Gateway → Enable and Deploy

• Workspace: Workspace Settings → MCP → Channel Gateway → toggle ON

Trigger Route

Credentials

• Authentication Type — How incoming requests are validated. Options: API Key, Basic Auth, Bearer Token, HMAC Signature, Public (no auth). Required.

• API Key — The expected API key value (shown when API Key is selected). Required.

• Username / Password — Basic auth credentials (shown when Basic Auth is selected). Required.

• Bearer Token — Expected bearer token value (shown when Bearer Token is selected). Required.

• HMAC Secret — Shared secret for HMAC signature validation (shown when HMAC Signature is selected). Required.

Route Settings

• Description — Optional label for this channel instance.

• Purpose — Optional note on when the agent should use this channel.

• API Key Validation Method — How the API key is delivered in incoming requests: Query Parameter or Header. Default: Query Parameter.

• HMAC Algorithm — SHA-1, SHA-256, or SHA-512. Default: SHA-256.

• HMAC Header Name — HTTP header containing the HMAC signature. Default: x-hub-signature-256.

• Source Label — Optional label to tag incoming events.

• Payload Extraction Path — JSON path to extract a specific field as the agent input. Optional.

• Initial Message — Prompt prefix prepended to the webhook payload. Optional.

Conversation Route

Credentials (outbound authentication to target URL)

• Outbound Authentication Type — How Neo authenticates when posting replies: API Key, Basic Auth, Bearer Token, or Public. Required.

Route Settings

• Description — Optional label for this channel instance.

• Purpose — Optional note on when the agent should use this channel.

• Target URL — The URL Neo posts agent replies and HITL approval requests to. Required.

• HTTP Method — POST, PUT, or PATCH. Default: POST.

• Body Format — JSON or Form URL Encoded. Default: JSON.

• Session Expiry (hours) — Idle timeout before a session resets. Default: 4. Range: 1–168.

• Timeout (ms) — Outbound request timeout. Default: 10000. Range: 1000–60000.

• Max Retry Attempts — Retries on delivery failure. Default: 3. Range: 0–10.

Neo delivers two payload types to the target URL. Use the message_type field to distinguish them. For full HITL template and placeholder reference, see Channel Delivery Templates.

Conversation reply (message_type: "conversation"):

{
  "message_type": "conversation",
  "session_id": "<session-uuid>",
  "message": "<agent reply text>"
}

HITL approval request (message_type: "hitl"):

{
  "message_type": "hitl",
  "session_id": "<session-uuid>",
  "hitl_execution_id": "<execution-id>",
  "title": "<approval title>",
  "description": "<AI-generated reply>",
  "callback_url": "<POST back here with decision>"
}

To approve or reject, POST to callback_url with:

{
  "session_id": "<session-uuid>",
  "hitl_context": {
    "action": "approve",
    "execution_id": "<hitl_execution_id>",
    "actor_id": "<reviewer-id>",
    "actor_name": "<reviewer-name>",
    "edited_response": "<modified reply or omit>"
  }
}

Notification Route

Route Settings

• Description — Optional label for this channel instance.

• Purpose — Optional note on when the agent should use this channel.

• Target URL — The URL Neo posts notifications to. Required.

• HTTP Method — POST, PUT, or PATCH. Default: POST.

• Body Format — JSON or Form URL Encoded. Default: JSON.

• API Key Delivery — How the API key is sent in outbound requests: Header or Query Parameter. Default: Header.

• API Key Header Name — Header name for the API key. Default: X-API-Key.

• Timeout (ms) — Request timeout. Default: 10000. Range: 1000–60000.

• Max Retry Attempts — Retries on failure. Default: 3. Range: 0–10.

• Retry Delay (seconds) — Delay between retries. Default: 60. Range: 10–600. Only shown when Max Retry Attempts > 0.