Webhook

The webhook channel is a generic HTTP integration layer. It lets any external system send messages to Talon by posting JSON to an HTTP endpoint, and Talon sends responses back to a URL of your choice. This is the escape hatch for systems that don’t have a dedicated Talon channel — custom applications, automation platforms, home automation systems, CI/CD pipelines, and so on.

How It Works

Incoming (Receiving Messages)

Talon listens for POST requests on the path you configure as incoming_path. The request body should be a JSON object with at minimum a message field:

{
  "message": "What is the weather today?",
  "user_id": "optional-user-identifier",
  "conversation_id": "optional-conversation-identifier"
}

When Talon receives the request it validates the secret (if configured), passes the message to the AI agent, and processes the response.

Outgoing (Sending Responses)

After the agent produces a response, Talon sends an HTTP POST request to the URL configured as outgoing_url. The payload is a JSON object:

{
  "message": "The agent's response text",
  "conversation_id": "the-conversation-identifier"
}

Your external system is responsible for handling this callback and doing something with the response — displaying it in a UI, forwarding it to another service, triggering an action, etc.

Setup

No external accounts or developer portals are required. The only prerequisite is that the machine running Talon is reachable on the network for incoming requests (or you are making requests from the same machine).

Example Config

{
  "channels": {
    "webhook": {
      "accounts": {
        "my-integration": {
          "incoming_path": "/webhook/my-integration",
          "outgoing_url": "https://my-app.example.com/talon-response",
          "secret": "a-long-random-secret-string"
        }
      }
    }
  }
}

With this config, Talon listens for POST requests at:

http://your-talon-host/webhook/my-integration

And sends responses to:

https://my-app.example.com/talon-response

Configuration Fields

Field	Required	Description
`incoming_path`	Yes	URL path where Talon listens for incoming `POST` requests
`outgoing_url`	Yes	URL where Talon sends `POST` requests with agent responses
`secret`	No	Shared secret for validating incoming requests
`model`	No	Override the default AI model for this account

Request Authentication

When secret is set, Talon includes the secret in an X-Talon-Secret header on all outgoing requests so your receiving system can verify they came from Talon.

For incoming requests, include the secret in the same X-Talon-Secret header. Talon rejects requests that are missing or have an incorrect secret.

curl -X POST https://your-talon-host/webhook/my-integration \
  -H "Content-Type: application/json" \
  -H "X-Talon-Secret: a-long-random-secret-string" \
  -d '{"message": "Summarize the latest news"}'

Conversation Continuity

Passing a consistent conversation_id in your incoming requests tells Talon to maintain context across multiple messages, just like a chat thread:

{
  "message": "What did I ask you before?",
  "conversation_id": "user-session-abc123"
}

If you omit conversation_id, each request is treated as a new conversation with no history.

Multiple Webhook Integrations

Add multiple entries under accounts to expose different webhook endpoints for different systems:

{
  "channels": {
    "webhook": {
      "accounts": {
        "home-automation": {
          "incoming_path": "/webhook/home",
          "outgoing_url": "http://192.168.1.10:8080/talon",
          "secret": "home-secret"
        },
        "ci-pipeline": {
          "incoming_path": "/webhook/ci",
          "outgoing_url": "https://ci.example.com/hooks/talon",
          "secret": "ci-secret"
        }
      }
    }
  }
}