Blog / channel guide
Hermes Agent Webhooks: Push Events Into Your Agent
Hermes Agent webhooks let an external system push an event into the assistant without polling. You create an endpoint, verify the shared secret or signature, map the payload into a prompt or task, and return quickly. The agent then answers in the channel you configured, such as Slack, Telegram, or email.
- 01
Pick one event worth automating
Start with a single high-signal event, such as a new support form submission or a failed nightly build, rather than wiring every possible notification.
- 02
Create the webhook endpoint in Hermes Agent
Generate the endpoint in the deployment settings, copy the signing secret, and note which channel the agent should reply into.
- 03
Verify the signature on every request
Compare the request signature against the shared secret with a constant-time check, and reject anything that does not match.
- 04
Shape the payload into a clear instruction
Send structured fields rather than a wall of text, and state the expected action so the agent does not have to guess intent.
- 05
Return fast and process asynchronously
Acknowledge the request immediately, then let the agent work. Long synchronous handling is the most common cause of duplicate deliveries.
- 06
Confirm the action in the target channel
Trigger the event once and verify the agent's reply or task appears where you expect, with the right context and no duplicate.
Four-step path
How do you send events to Hermes Agent with webhooks?
Five checkpoints: pick the event source, create the endpoint, verify the signature, shape the payload, then confirm the agent's action end to end.
- Step 01
Pick one event worth automating
Start with a single high-signal event, such as a new support form submission or a failed nightly build, rather than wiring every possible notification.
- Step 02
Create the webhook endpoint in Hermes Agent
Generate the endpoint in the deployment settings, copy the signing secret, and note which channel the agent should reply into.
- Step 03
Verify the signature on every request
Compare the request signature against the shared secret with a constant-time check, and reject anything that does not match.
- Step 04
Shape the payload into a clear instruction
Send structured fields rather than a wall of text, and state the expected action so the agent does not have to guess intent.
- Step 05
Return fast and process asynchronously
Acknowledge the request immediately, then let the agent work. Long synchronous handling is the most common cause of duplicate deliveries.
- Step 06
Confirm the action in the target channel
Trigger the event once and verify the agent's reply or task appears where you expect, with the right context and no duplicate.
When is a webhook better than a polling integration?
Use a webhook whenever the source can push and you want the agent to react within seconds. Polling wastes requests and adds latency for events that are naturally instantaneous.
- Form submissions, alerts, and CI results are ideal webhook triggers.
- Continuous data streams are usually better handled by a scheduled summarizer instead.
- Conversational channels such as Slack are better than webhooks when a human is the trigger.
- If the source cannot sign requests, put a small proxy in front of the endpoint.
How do you secure a Hermes Agent webhook?
Treat the endpoint as public. Require a signature or a bearer secret, reject replays with a timestamp window, and never put the secret in a query string that lands in logs.
- Verify the HMAC signature with a constant-time comparison.
- Reject requests whose timestamp is outside a short window.
- Store the secret as a secret, and rotate it if it is ever exposed.
- Rate limit the endpoint so a misconfigured source cannot flood the agent.
Why does the same event trigger the agent twice?
Webhook providers retry when they do not receive a fast success response. If your handler waits for the agent to finish, the source assumes a failure and sends the event again.
- Return a 2xx as soon as the payload is accepted.
- Deduplicate on the provider's event identifier before acting.
- Keep the processing window short and queue heavy work.
- Log every delivery so duplicates can be traced to the source.
What should the webhook payload contain?
Send the facts the agent needs and nothing more: an event type, an identifier, the relevant fields, and the requested action. Structured JSON keeps the prompt small and the behaviour predictable.
Avoid echoing entire documents into the payload. Send identifiers and let the agent fetch details from a system of record, which keeps context small and avoids stale copies of the truth.
How do you monitor a webhook integration?
Track delivery success, processing failures, and duplicate rate separately. A webhook that always returns 200 but never completes its work is worse than one that fails loudly.
Alert on the agent's downstream action, not only on the HTTP response. That is the signal that tells you the integration is genuinely healthy.
Which primary sources support this page?
Product behavior is checked against the current deployment flow. These external links provide the upstream project or channel documentation used for setup details.
Direct answers
Frequently asked questions
Can Hermes Agent receive webhooks without a public URL?
The endpoint must be reachable by the sending system. Managed deployments provide the address, so you do not have to run your own ingress.
Which events should I start with?
Pick one event with clear value and low noise, such as a new high-priority support request, then expand after the first integration is stable.
Can the agent respond in a chat channel instead of HTTP?
Yes. The webhook triggers the agent, and the reply can be delivered to Slack, Telegram, email, or another connected channel.
How do I rotate the webhook secret?
Generate a new secret in the deployment settings, update the sending system, confirm one successful delivery, then retire the old secret.
Key takeaways
- Hermes Agent webhooks let an external system push an event into the assistant without polling. You create an endpoint, verify the shared secret or signature, map the payload into a prompt or task, and return quickly. The agent then answers in the channel you configured, such as Slack, Telegram, or email.
- Start with one model, one channel, and one controlled test conversation.
- Use managed hosting when deployment speed matters more than operating the server yourself.
Continue the setup
Related Hermes Agent guides
Blog guide
Hermes Agent Email Setup: IMAP and SMTP Inbox Agent
Turn an inbox into a Hermes Agent channel with IMAP and SMTP, app passwords, safe folder rules, and a single-thread test before autonomous triage.
Read nextBlog guide
Hermes Agent Slack Setup: Socket Mode in Minutes
Connect Hermes Agent to Slack with Socket Mode, scoped bot tokens, and a private-channel test. Verify the runtime, fix missing replies, and scale to channels.
Read nextBlog guide
How to Choose a Hermes Agent Channel
Compare Telegram, Discord, and WhatsApp for Hermes Agent deployment. Choose the best channel for support, daily briefings, and team operations.
Read nextBlog guide
Hermes Agent API Access: Keys, MCP, and Programmatic Control
Understand programmatic access to Hermes Agent: API keys, MCP servers, CLI automation, and what a managed deployment does and does not expose.
Read next