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, Coworker
• Route types: Trigger, Conversation, Notification
• Auth: API Key, Basic Auth, Bearer Token, HMAC Signature, or Public

Route Overview

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.

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. Default: API Key. Required.

The same setting also checks requests your system sends to the conversation route. Send the key, token, or credentials in the Authorization header: Bearer <token> for Bearer Token, Basic <base64 user:password> for Basic Auth, or the API key itself for API Key. To accept requests with no authentication, choose Public explicitly — a credential with no authentication type is rejected.

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.