> ## Documentation Index
> Fetch the complete documentation index at: https://agentheya.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```http theme={null}
Authorization: Bearer your-api-key
```

or

```http theme={null}
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](/sidebar-menu/event-pre-processor) 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](/sidebar-menu/event-interpreters) 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

<Note>Owner-only advanced control.</Note>

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`:

```bash theme={null}
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":"test@example.com"}}}'
```

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](/manage-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](/manage-mcp) for authentication and the full tool catalogue.