How to Connect Hermes Agent to Jira With Webhooks

Over 107,000 companies use Jira in their tech stacks, making it the most widely adopted project collaboration tool on the market. Nous Research Hermes Agent, the open-source (MIT-licensed) AI agent that runs on your own infrastructure, lists Jira among its supported webhook sources. But the official Hermes documentation stops at a name in a list. There are no Jira-specific route examples, payload templates, or setup instructions. Only GitHub and GitLab get full walkthroughs.

This guide fills that gap. By the end, you will have a Hermes webhook route that receives Jira issue events, a prompt template that extracts the fields your agent needs, and a delivery pipeline that sends the agent's analysis to whichever platform your team actually uses.

The webhook approach handles real-time event notifications. When a Jira issue is created, updated, or transitioned, Jira posts the event payload to your Hermes instance. The agent processes the payload using your prompt template, applies whatever skills you have loaded, and delivers its response. The entire loop runs without polling, without scheduled checks, and without manual triggers.

A separate integration path exists through Composio, which gives Hermes structured API access to Jira for actions like creating issues, running JQL queries, and managing sprints. This guide focuses on the inbound webhook path, where Jira pushes events to Hermes and the agent reacts.

The webhook adapter is a lightweight HTTP server built into the Hermes messaging gateway. It listens on a configurable port (default 8644), accepts POST requests at route-specific endpoints, validates signatures, renders prompt templates from the incoming payload, runs the agent, and delivers the response to a target platform.

Each route maps to a URL path: http://your-server:8644/webhooks/<route-name>. When a POST arrives, the adapter checks that the route exists, validates the HMAC signature against the route's secret, filters by event type if the route defines an event list, renders the prompt template using dot-notation field access from the payload, runs the Hermes agent with the rendered prompt, and delivers the response to the configured platform.

Routes are defined in ~/.hermes/config.yaml under platforms.webhook.extra.routes, or created dynamically with hermes webhook subscribe. Both produce the same result. Config file routes load at startup. CLI subscriptions are stored in ~/.hermes/webhook_subscriptions.json and hot-reload on each incoming request.

The adapter enforces rate limiting at 30 requests per minute per route by default, deduplicates requests using X-Request-ID headers with a one-hour cache, and rejects payloads larger than 1 MB. Signature validation uses HMAC-SHA256 for generic sources (anything that is not GitHub or GitLab), checking the X-Webhook-Signature header against the route's secret.

The deliver field controls where agent responses go. Hermes supports 24 platforms: Slack, Telegram, Discord, Microsoft Teams, WhatsApp, Signal, SMS, Email, Matrix, Mattermost, DingTalk, Feishu, WeCom, Weixin, BlueBubbles, QQ Bot, Yuanbao, LINE, SimpleX Chat, Google Chat, Home Assistant, IRC, Open WebUI, and plain log output. Any of these can receive Jira-triggered agent analysis.

Enable the webhook adapter and create a route for Jira events. Add this block to ~/.hermes/config.yaml:

platforms:
  webhook:
    enabled: true
    extra:
      port: 8644
      routes:
        jira-issues:
          secret: "your-jira-webhook-secret"
          prompt: |
            A Jira issue event was received.
            Event: {webhookEvent}
            Issue: {issue.key}
            Summary: {issue.fields.summary}
            Status: {issue.fields.status.name}
            Priority: {issue.fields.priority.name}
            Assignee: {issue.fields.assignee.displayName}
            Reporter: {issue.fields.reporter.displayName}
            Description: {issue.fields.description}

Analyze this issue. If it is a bug report, assess
            severity and suggest which team should own it. If it
            is a feature request, summarize the ask and flag
            any dependencies.
          deliver: slack
          deliver_extra:
            channel: "#jira-triage"

The key fields in this configuration:

secret: The HMAC key used to validate incoming requests. The adapter checks the X-Webhook-Signature header for generic webhook sources.

prompt: A template using dot-notation to extract fields from the Jira webhook payload. {issue.fields.summary} pulls the issue title. {issue.key} gives the project key and number like PROJ-123. Missing keys stay as literal {key} strings in the rendered prompt, so you can spot mismatched field paths quickly.

deliver: Where the agent sends its response. Set this to slack, telegram, discord, email, teams, or any of the other supported platforms.

deliver_extra: Platform-specific settings like the target Slack channel or Telegram chat ID. These fields also support dot-notation template variables from the payload.

You can also create the route from the command line:

hermes webhook subscribe jira-issues \
  --prompt "Issue {issue.key}: {issue.fields.summary} ({issue.fields.status.name}). Triage this issue and recommend priority." \
  --deliver slack \
  --deliver-chat-id "#jira-triage"

Start the gateway if it is not already running:

hermes gateway run

Verify the endpoint is live:

curl http://localhost:8644/health

This should return {"status": "ok", "platform": "webhook"}.

Persist your Jira triage output across sessions

Free 50 GB workspace with auto-indexing. Upload Hermes Agent's analysis, search it by meaning, and hand it off to your team when it's ready. No credit card, no expiration.

Sign Up Free

With the Hermes route ready, point Jira at it.

Jira Cloud

Log in as a Jira admin. Navigate to Settings > System > WebHooks (under Advanced). Click "Create a WebHook" and configure:

• Name: Hermes Agent Triage
• URL: https://your-server:8644/webhooks/jira-issues
• Events: Select "Issue created" and "Issue updated" to match the route
• JQL filter (optional): Scope the webhook to specific projects or issue types, such as project = SUPPORT AND issuetype = Bug

Jira sends event types like jira:issue_created, jira:issue_updated, comment_created, sprint_started, and sprint_closed in the webhookEvent field of the payload body. If you set the events list on the Hermes route, the adapter filters incoming requests against those values. Leaving the list empty accepts all events on the route.

Signature Validation Jira's native webhooks do not include HMAC signature headers. This creates a mismatch with the Hermes adapter, which checks the X-Webhook-Signature header for generic sources. Three approaches bridge this gap:

Reverse proxy with signing (recommended for production): Place a lightweight proxy between Jira and Hermes, such as nginx, Caddy, or a small Python service. The proxy receives Jira's POST, computes the HMAC-SHA256 hex digest of the body using your shared secret, adds the X-Webhook-Signature header, and forwards the request to Hermes. This keeps HMAC validation intact without modifying Jira.

Jira Automation rules: Instead of the system-level webhook, create a Jira Automation rule with a "Send web request" action. Automation rules allow custom headers on the outgoing request, giving you a path to include a pre-shared token or static signature value.

Network-level restriction: If Hermes runs on the same private network as your Jira instance (common with Jira Data Center), restrict access to the webhook port by IP. This does not replace HMAC but adds a defense layer. For local development, the adapter accepts "INSECURE_NO_AUTH" as the route secret, but only on loopback addresses like 127.0.0.1.

Jira Server and Data Center

The admin path may differ: click the Administration cog, then System > WebHooks. Jira Data Center 10.0 and later processes webhooks asynchronously by default through a dedicated thread pool, which improves reliability under load but adds a small delay between the Jira action and webhook delivery.

Test by creating an issue in the scoped project, then check your delivery platform for the agent's response.

The prompt template determines what context the agent receives and how it responds. Jira webhook payloads include the full issue object, user information, and changelog entries for updates.

Jira Payload Field Reference

Common dot-notation paths:

• {webhookEvent}: Event type, e.g., jira:issue_created
• {issue.key}: Issue key like PROJ-123
• {issue.fields.summary}: Issue title
• {issue.fields.description}: Full description text
• {issue.fields.status.name}: Current status like "To Do" or "In Progress"
• {issue.fields.priority.name}: Priority level
• {issue.fields.issuetype.name}: Issue type (Bug, Story, Task, Epic)
• {issue.fields.assignee.displayName}: Current assignee
• {issue.fields.reporter.displayName}: Who filed the issue
• {issue.fields.labels}: Attached labels as a JSON array
• {changelog.items}: Changed fields, present only on jira:issue_updated events
• {user.displayName}: The user who triggered the event

Nested structures serialize to JSON, truncated at 2,000 characters. The {__raw__} token dumps the entire payload (truncated at 4,000 characters), which is useful for debugging field paths.

Status Transition Alerts Without Agent Processing

For simple notifications that skip the LLM entirely, set deliver_only: true on the route. The rendered prompt becomes the literal message with sub-second delivery and zero inference cost:

routes:
  jira-status-alert:
    secret: "your-secret"
    events:
      - jira:issue_updated
    prompt: "{issue.key} moved to {issue.fields.status.name} by {user.displayName}"
    deliver: telegram
    deliver_extra:
      chat_id: "-100123456789"
    deliver_only: true

This sends a plain text message to Telegram every time an issue changes status. Useful for keeping a channel updated on sprint progress without spending inference tokens.

Combining Event Types on One Route

You can handle multiple event types with a single route and let the prompt guide the agent's behavior:

Jira event: {webhookEvent}
Issue: {issue.key} - {issue.fields.summary}
Type: {issue.fields.issuetype.name}
Priority: {issue.fields.priority.name}
Status: {issue.fields.status.name}
Description: {issue.fields.description}

If this is a new bug, classify by component and estimate severity.
If this is a status change, summarize what moved and flag blockers.
If this is a new feature request, extract the core ask in one sentence.

The agent reads the {webhookEvent} value and adjusts its response accordingly.

The deliver field routes agent responses to a chat platform, which works for real-time notifications. But analysis that needs to persist longer than a Slack thread requires file storage.

When Hermes triages dozens of issues over a week, that output has value beyond the moment it was delivered. Sprint summaries, severity assessments, and dependency maps are reference material that teams revisit during planning. Storing this output in files gives it a longer shelf life than a chat message buried in a busy channel.

Local file storage works if your Hermes instance runs on a single server and you are the only consumer. S3 or Google Cloud Storage handles durable archival. But if the output needs to reach people who were not in the chat, or if you want agents and humans working from the same documents, a shared workspace fits better.

Fast.io provides intelligent workspaces where uploaded files are indexed automatically for semantic search and AI chat. Your team can find last Tuesday's sprint summary by asking "what blocked the API team in sprint 14?" instead of scrolling through Slack history. The Fast.io MCP server gives Hermes programmatic access to upload files, create shares, and query workspace contents.

The practical setup: configure Hermes to write its Jira analysis to local files using a file-writing skill or the terminal tool, then sync those files to a Fast.io workspace via MCP or the Fast.io API. With Intelligence Mode enabled, the workspace becomes a searchable knowledge base of every triage decision the agent has made.

The free tier includes 50 GB of storage, 5,000 AI credits per month, and 5 workspaces, with no credit card and no expiration. When the project is ready to hand off, ownership transfer moves the workspace from the agent's account to a human team lead while keeping admin access for continued automation.