Agents
Guide

Agent Webhooks

Trigger Agent runs over authenticated HTTP with signed request verification, idempotency controls, and native platform delivery.

For
Agent operators, API developers, and automation engineers
On this page
  1. Overview
  2. How webhook triggers work
  3. Authentication and request signing
  4. Request payload & idempotency
  5. Invocation states & retries
  6. Related documentation

Configure signed inbound HTTP webhooks to trigger Agent runs from external CI/CD pipelines, alert systems, and custom automation.

Overview

An Agent Webhook lets an external service trigger a headless Agent over authenticated HTTP. Agent Barn verifies request authenticity, enforces idempotency, and records submission history. The underlying runtime (Hermes or OpenClaw) executes the resulting one-shot trigger job in an isolated session and delivers the reply to the platform's configured default channel.

How webhook triggers work

Webhook triggers follow a decoupled admission flow:

  • Admission & Ingress: The Product API receives the signed JSON payload, validates the HMAC signature and timestamp window, and atomically creates a Webhook Invocation record.
  • Private Dispatch: Agent Barn submits the request to the Agent's authenticated internal trigger listener on Kubernetes. Transient transport failures are retried up to three times.
  • Isolated Execution: Hermes or OpenClaw schedules a deterministically named one-shot job. When complete, the final response is posted directly to the selected platform connection (e.g. Slack, Teams, Telegram, or Discord).

Webhook triggers never create Communication Deliveries and do not pass through the Communications Gateway or Platform Plugin registry.

Authentication and request signing

Every webhook request must include the X-AgentBarn-Timestamp header (Unix epoch seconds) and an HMAC-SHA256 signature in the X-AgentBarn-Signature header.

The signature is computed over {X-AgentBarn-Timestamp}.{raw_request_body} using the webhook's signing secret. Requests with timestamps differing by more than 300 seconds from server clock time are rejected to prevent replay attacks.

Request payload & idempotency

The JSON request payload accepts the following fields:

  • prompt (required): Plain text instructions for the Agent, capped at 5,000 characters.
  • event_id (optional): External unique event ID. When provided, retried requests with the same ID return the existing invocation without resubmitting duplicate jobs.

Invocation states & retries

Invocations transition through a simple state model:

  • RECEIVED: Accepted by the API and queued for dispatch to the Agent.
  • SUBMITTED: Durably accepted by the runtime's native scheduler. This is terminal in Agent Barn; execution proceeds inside the runtime.
  • DISPATCH_FAILED: Submission could not be accepted. Eligible for explicit retry in the dashboard or API.

See Configure an Agent, Agent lifecycle, and Communication Connections.

Documentation