Can an external service trigger my AI agent?

Yes. Hermes has a built-in webhook server. Enable it, set a secret, and define routes that map incoming requests to what the agent should do.

Is it safe to expose a webhook endpoint?

Only with a secret set. An unauthenticated endpoint that triggers an AI agent can be called by anyone who finds it, consuming your model credits.

← Home

Guide

Connect Webhooks to Your AI Agent

Q: Do webhooks need a public URL?

Yes. The sending service must reach your agent, so the webhook port needs to be exposed over public HTTPS. A tunnel such as Cloudflare Tunnel works without owning a domain.

Webhooks are the other direction. Instead of a person messaging the agent, a system does — a deploy finishes, a payment fails, an alert fires, and the agent picks it up and acts.

What This Is Good For

Anything that can send an HTTP request can now start a conversation with your agent. A few that people actually build:

A monitoring alert arrives and the agent triages it and messages you on Telegram with a summary.
A pull request opens and the agent reviews the diff and posts back.
A payment fails and the agent drafts the customer email for you to check.
A form submission arrives and the agent files it where it belongs.

Turn On the Webhook Server

Run the guided setup from your instance's Web Terminal:

hermes gateway setup

Or set it directly:

WEBHOOK_ENABLED=true
WEBHOOK_PORT=8644
WEBHOOK_SECRET=your-global-secret

Set the secret. An open webhook endpoint is an open door to your agent's time and your model credits, and anything that can reach the port can make it do work.

Define Routes

A route maps an incoming request to what the agent should do with it. You can define them in the config file, or create them on the fly:

hermes webhook subscribe

Think of the route as the instruction attached to the payload. The sending service knows nothing about your agent; the route is where you say what an incoming GitHub event or alert actually means and what should happen next.

Make It Reachable

This is the part that bites. The sending service has to reach your agent, which means the webhook port needs to be exposed over public HTTPS. A tunnel such as Cloudflare Tunnel is the simplest route and needs no domain of your own. Contact support and we can help arrange this for your instance.

Do not expose the port without the secret set. Bots scan for open endpoints constantly, and an unauthenticated webhook that triggers an AI agent is an expensive thing to leave lying around.

Test It

Send a request yourself before wiring up the real service — a simple POST with your secret and a small JSON body tells you whether the server is up, whether the secret matches and whether the route fires, in one go. Once that works, point the real service at the same URL.

Troubleshooting

The service reports a delivery failure. The endpoint is not reachable from the internet, or the tunnel dropped.
Requests are rejected. The secret does not match what the sender is sending.
Delivered but nothing happens. No route matches the incoming path, so the payload lands nowhere.
The agent misreads the payload. Say explicitly in the route what the data is and what to do with it — a raw JSON blob with no instruction gets guesswork.
Unexpected usage. Something is calling your endpoint. Rotate the secret.

Need a Hand?

Contact support from your dashboard and we will get the webhook server up and reachable for you.