◆ Sparround

Webhooks and event hooks

Cron fires on time. But most work is tied not to time but to an event: a PR was opened, a payment failed, monitoring raised an alert. There are two different mechanisms for that, and they are easy to confuse:

  • Webhooks — an incoming HTTP request activates the agent (hermes webhook)
  • Hooks — your own code runs at a defined point in the agent's lifecycle (hermes hooks)

The first answers "when should it run", the second answers "what should happen while it runs".

CriterionWebhookHook
DirectionInboundInternal, during execution
TriggerAn HTTP request from an outside systemA point in the agent's lifecycle
Typical useCI finished, a ticket was opened, an alert firedLogging, notifications, guardrails
The key security questionWho may call this endpoint?What can it block?

Hooks are the least known mechanism and the most valuable one in a corporate setting: they attach your code to points in the agent's lifecycle — for logging, alerting, calling an external webhook, and for guardrails. The audit answer to "what did this agent do?" is usually built out of hooks.

Note: a hook is code under your control, not the agent's. That makes it the right place to enforce a security policy — the model cannot talk its way past it.

The first question when setting up a webhook is always the same: who can call this endpoint? Any HTTP request that activates the agent is, in effect, giving the agent a task. So a webhook's input is untrusted data — the text arriving there must be treated as data rather than a command, and processed with the narrowest possible toolset.

Practice. Write a hook that appends every executed terminal command — with a timestamp, the command and the result — to a separate audit file. Then run a few sessions and read the file. Done means: from the audit file you can reconstruct which commands the agent ran that day.

📚 Sources and documentation