Webhook Triggers

Receive HTTP requests from any external service and have your agent process them automatically.

Overview

A webhook trigger gives your agent a unique URL it listens on. When an external service POSTs (or otherwise hits) that URL, the agent receives the request body and can act on it — reply, store data, trigger a workflow, and so on.

The URL is generated for you when you create the trigger and shown in the card. Click the copy icon next to it to copy. Each agent’s URLs are distinct, and each trigger has its own URL; create as many as you need.

To add a trigger, click Add Webhook on the page, give it a name, and click Save. Each card has an ON / OFF toggle, drag-to-reorder, and a delete button.

Authentication uses any API key from your API Keys page. Pass it in the request:

Authorization: Bearer your-api-key

or

X-Webhook-Key: your-api-key

---

Processing pipeline

Each webhook card exposes the shared incoming-event pipeline. Every request flows through these stages in order before (and around) the agent:

Event pre-processor

Optional owner-supplied code that runs in a sandbox before the classifier and the agent see the request. Define handle(event, ctx) and return a verdict — pass_to_agent, drop, store, run_tool, or respond (a synchronous HTTP reply). A drop here happens before, and skips, the classifier — the cheapest place to filter health-check pings or noise. See the Event pre-processor guide for the full contract, the event/ctx objects, and worked examples.

Interpreters

When one webhook receives several different kinds of payload, Interpreters recognise each kind and inject a plain-language hint into the agent’s context so it knows what it’s looking at before it reads the body. Each interpreter matches by JSON field presence (dot-paths) or regex (any body format), tested in order — first match wins.

See the Interpreters guide for the full matching rules and worked examples (Shopify, Stripe, form-encoded, XML, CSV, GitHub, and more). Leave interpreters empty when every payload on this webhook is the same kind of thing — use Context instead.

Event classifier

Optional. When enabled, an LLM reads each request before the agent runs and picks an action from the allow-list — React (hand it to the agent), Store (keep it in the inbox without running the agent), or Drop (ignore it, still logged). Off → every request goes straight to the agent. Give it a prompt describing what counts as relevant, e.g. “Only react to payment.succeeded and refund events; drop everything else.”

Context and Notes

Two free-text fields at the bottom of each card:

• Context — instructions for the agent that apply to every call on this webhook (e.g. “These are GitHub push events. Extract the repository name and commit message.”). Prepended to the agent’s context for every incoming payload.
• Notes — private operator notes, never seen by the agent.

Use Context when every payload on this webhook is the same kind of thing. Use Interpreters when one webhook receives different event types.

Spend budget

Owner-only advanced control.

Each trigger can carry its own AI spend cap so a runaway or abused webhook can’t drain your credits. Set a Spend cap (credits) and a Budget period — Daily, Weekly (Mon–Sun), or Monthly (calendar month). Once the cap is reached for the current period, further deliveries are still acknowledged (so the caller sees a 200) but not processed by the agent, until the period resets at UTC boundaries. Leave the cap at 0 for no limit.

Testing your webhook

You can test any webhook trigger with curl:

curl -X POST https://api.agentheya.com/webhook/wh-youragentid-yourtokenhere \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"order":{"id":1001,"line_items":[{"sku":"T-SHIRT"}],"customer":{"email":"[e-mail]"}}}'

Recent deliveries appear in Recent Webhook Events on the Webhook Triggers page — a table of time, method, source IP, auth verdict, outcome (→ agent / dropped / stored / responded / ran tool), event name, and detail — and in the Inbox for the trigger’s conversation thread.

Manage via the Management MCP

This area is managed through the Management MCP at https://manage.agentheya.com/mcp.

Endpoint	https://manage.agentheya.com/mcp
Tools	list_webhook_triggers, add_webhook_trigger, remove_webhook_trigger

All tools take owner_id + agent_id as required arguments. See the Management MCP guide for authentication and the full tool catalogue.