AI Agent Webhooks: Let the Internet Trigger Your Agent

Most people only ever talk to their AI agent. You type, it replies, done. There is a whole other mode where the internet itself wakes your agent up — a new customer signs up and your phone buzzes with the details, a pull request opens and the agent has already reviewed it, a sale lands and the numbers update without anyone asking. That is what AI agent webhooks do, and once you wire the first one you stop thinking of your agent as a chat window.

The payoff in the first minute: webhooks turn your agent from something you summon into something that responds to your business in real time, with no polling and no babysitting. Here is how the two halves work, and the one architectural distinction that makes the rest obvious.

A webhook is a doorbell

The clearest way to think about it: a webhook is a doorbell. Polling is you walking to the front door every five minutes to check if anyone is there. For real-time events — sales, subscribers, PRs, payments — the doorbell wins by orders of magnitude. You are not burning runs on "nope, still nobody," and you find out the instant something happens.

There are two directions, and keeping them straight saves you a lot of confusion:

• Inbound. An outside platform calls your agent. New subscriber, new PR, new payment. This needs a public URL so the platform can reach you.
• Outbound. Your agent calls an outside service. It pulls data, reasons over it, and POSTs the result somewhere. This needs no public URL at all — the agent just makes an HTTP call like any client.

Mixing these up is the most common stumbling block. Say it plainly: inbound needs a tunnel, outbound does not.

Inbound: wiring an event to wake your agent

Three steps. Register a route, expose a public URL, tell the platform where to knock.

First, declare the route in your config so the agent knows what to do when the event arrives:

# .hermes/config.yaml
platforms:
  webhook:
    enabled: true
    port: 8644
    secret: <your-generated-secret>
routes:
  - name: new-subscriber
    prompt: "New {{platform}} subscriber: {{email}} from
             {{referral_source}} (tier: {{tier}}) at {{timestamp}}.
             Ping me in Telegram."

Those {{double_brace}} tokens get filled from the incoming JSON payload at delivery time. So a raw webhook from your newsletter platform turns into a clean, human-readable ping with the email, the referral source, and the tier already pulled out.

Second, expose a public URL. For inbound you need a tunnel because the outside platform has to reach your machine:

ngrok http 8644
# copy the https URL it prints

Register that URL in the platform's webhook settings, usually as <ngrok-url>/webhook/new-subscriber, then restart the gateway. One sharp edge to know up front: ngrok's free tier hands you a new URL every time it restarts. When it rotates, you have to update the URL in every platform you registered it with. For anything you intend to keep running, get a stable URL so you are not re-registering all day.

Third, test it with the platform's "send test webhook" button before you trust it. If no ping arrives, check the gateway logs — that is where a bad secret or a typo'd route shows up.

Security: HMAC, and where the secret lives

Anyone who finds your URL can hit it, so the agent has to verify that a request genuinely came from the platform. That is what HMAC signing is for, and the receiver handles the verification automatically once the secret is set. Your job is just to generate a strong secret and put the same value in both places.

# 64-char hex secret
python -c "import secrets; print(secrets.token_hex(32))"

The exact same secret goes in your .hermes/.env and in the third-party platform's webhook settings. If they do not match, every request fails the signature check and nothing fires — which, annoyingly, looks exactly like "the webhook is broken." Check the secret first when an inbound route goes silent.

A real one: GitHub PR auto-review

This is the inbound webhook that earns its place fastest if you ship code.

A pull request opens. The webhook fires. The agent reads the diff through the GitHub CLI, judges correctness, flags anything risky, and posts a draft review comment on the PR. You read the agent's comment before you merge. It does not approve or merge on its own — it does the first pass so you are reviewing a review, not a raw diff.

routes:
  - name: github-pr
    prompt: "Review PR {{repo}} #{{number}} by {{author}}.
             Fetch the diff, assess correctness, suggest improvements,
             and flag risks. Post a draft review comment."

In the repo, go to Settings → Webhooks, set the secret to match your config, choose the application/json content type, and subscribe to the Pull requests event only. Scope it tight. The agent never needs the firehose of every repo event to do this job.

This pairs naturally with multi-agent orchestration once you are reviewing many PRs across repos — the webhook drops a card, a reviewer agent claims it, and a durable board tracks what got reviewed.

Outbound: the agent in the loop, not just a relay

Outbound is where the agent stops being a notifier and starts adding judgment. And it is simpler to run, because there is no tunnel.

The shape: a scheduled job pulls a data source, the agent reasons over it, and it POSTs structured JSON to your app's endpoint with an HMAC signature. Your app verifies the signature and displays the result. No ngrok, because the agent is the one making the call.

# .env
AGENT_WEBHOOK_URL=https://yourapp.com/api/agent-updates
AGENT_WEBHOOK_SECRET=<shared-secret>

The thing that makes this worth doing is the reasoning step. Do not just relay raw data — anyone can write a scraper. Make the agent think:

Analyze these RSS articles and identify the top 10 keywords likely to
trend this week. Return only valid JSON matching:
{ "keywords": [ { "word": string, "confidence": float, "reasoning": string } ] }

That is the line between a cron that copies data and an agent that produces a signal. The agent has to read the articles, weigh them, and explain itself. On the app side, verify the x-agent-signature HMAC before you trust a single byte of it, exactly as you would for inbound.

When to reach for a webhook vs. a schedule

Quick decision: if the trigger is "something happened out there," use an inbound webhook. If the trigger is "it is now this time," use cron. If your agent needs to push a reasoned result somewhere on a schedule, that is an outbound webhook driven by a cron — the two patterns compose.

And keep the same safety rule you use everywhere else: webhooks can wake the agent and let it draft, notify, or analyze, but the actions that matter — sending, posting, deploying, spending — stay behind a human gate. See least-privilege agent design for how to scope that cleanly.

FAQ

What is an AI agent webhook?

It is an HTTP callback that lets an outside service trigger your AI agent the moment an event happens (inbound), or lets your agent push a result to another service (outbound). It replaces polling with instant, event-driven action.

Do I need ngrok for AI agent webhooks?

Only for inbound. An outside platform needs a public URL to reach your agent, so inbound requires a tunnel like ngrok. Outbound webhooks are just the agent making an HTTP call, so they need no tunnel at all.

How do webhooks stay secure?

With HMAC signing. You generate a shared secret, store it in both your agent's environment and the platform's webhook settings, and the receiver verifies every request's signature. Requests that fail the check are rejected automatically.

What's a good first AI agent webhook to build?

A new-subscriber or new-sale ping (inbound) is the fastest win — it turns a real business event into an instant, formatted notification. GitHub PR auto-review is the best one for developers.

Get the webhook patterns as real files

You can spend an afternoon fighting ngrok URL rotation and mismatched HMAC secrets, or you can start from working examples. OpenClawCrew starter kits ship the inbound route config, the GitHub PR reviewer, and the outbound enrichment pattern as editable files set up for Hermes or OpenClaw, with the security wiring already done. Grab the $49 starter kit to build it yourself, or book a done-for-you setup and have your agent answering the doorbell this week.

Related reading: AI agent cron automation, multi-agent orchestration, connecting your agent to your tools, and agent security.