Webhooks integration

Webhooks and AI agents: start runs, deliver answers, trigger systems

Webhooks work in three directions. Webhook (in) lets another system start a run by POSTing signed JSON to the app's receiver. Webhook (out) posts every finished answer as signed JSON to a URL of yours. And a webhook tool lets the agent trigger your system in the middle of a conversation. All three are recorded: inbound events with their outcome, deliveries as steps, tool calls with request and response.

Tool type
Channel nodes
Auth type
HMAC-SHA256 signature with an integration secret (shown once); webhook tools use a shared-secret header
Safety level
channel nodes; webhook tools carry write_safe and optional approval

What you can build

An order-triage app: your order system posts each new order to Webhook (in), the agent answers, and Webhook (out) posts the triage back to your system, on one thread per order.

A support assistant whose every answer is mirrored to your data warehouse or ticketing system through Webhook (out).

An agent that hands a qualified lead to your automation platform (Zapier, Make, n8n or your own endpoint) through a webhook tool once the user asks to be contacted.

How to connect Webhooks

  1. 01Create a webhook integration under Integrations (or from the node itself). Its signing secret is shown once; keep it where your system can sign and verify.
  2. 02To start runs: put Webhook (in) before Chat (in), pick the integration, and set the paths that read the input, the thread key and the identity out of your payload. POST signed JSON to the receiver URL on the app's Credentials tab; the tab shows a signing example and the latest events.
  3. 03To deliver answers: connect Webhook (out) to Chat (out), pick the integration, set the URL (https, or http to localhost while developing) and what to include. Verify X-AgentRow-Signature on your side with the secret.
  4. 04For server runs from your backend, no node is needed: call the server-run endpoint with the app secret; an async run's callback URL is delivered by a Webhook (out) with target callback URL.
  5. 05To let the agent trigger your system, create a tool of type webhook with the target URL, an event name, an input schema and a safety level; mark it as requiring approval if a human must confirm each trigger.

Example tool definition

The shape a tool takes in the AgentRow builder API. Credentials are stored on the tool's auth settings, not in its configuration, so they never reach a prompt. Placeholders in double braces are filled by the model from the input schema.

[
  {
    "id": "webhook_in",
    "type": "webhook_in",
    "config": {
      "integration_id": 3,
      "signature_scheme": "agentrow_hmac_sha256",
      "replay_window_seconds": 300,
      "input_path": "input",
      "thread_key_path": "thread_key",
      "dedupe_key_path": "event_id"
    }
  },
  {
    "id": "webhook_out",
    "type": "webhook_out",
    "config": {
      "integration_id": 3,
      "target": "fixed_url",
      "url": "https://hooks.example.com/agentrow/answers",
      "sign": true,
      "include": ["output", "run", "thread"]
    }
  }
]

What the run trace shows

Every turn shows its channel on the Chat (in) step (source, thread, caller), and every delivery is its own step after Chat (out) with the request, the channel's response, timing and a named error when it failed. Inbound events are listed on the app's Credentials tab with their outcome: accepted, duplicate or rejected, each with its reason.

Frequently asked questions

Can I trigger an AgentRow agent from a webhook?

Yes. Webhook (in) is the receiver: signed JSON starts a run on the thread your payload names. A repeated event id answers 'duplicate' and starts nothing, and unsigned or stale requests are refused by name.

Does a failed delivery fail the run?

No. Webhook (out) runs after the answer is complete. A failed delivery is a failed step with a named error and the HTTP status; the run keeps its answer and any other delivery still runs. Deliveries are not retried automatically.

Can a webhook tool return data to the agent?

The response body is recorded and returned to the model like any tool result, so a synchronous receiver can answer with data. For long-running work, return a job id and let the user ask about it later.

Connect Webhooks to your first agent

Start a free trial and wire it up, or tell us which systems you need to connect and we will point you at the right tool definitions.