Wiki · Funkce do hloubky
Webhooky
Webhook je dveře do vašeho agenta. Jak je zamknout, komu je otevřít a co má agent udělat, když něco zaklepe.
🪝
Webhook je dveře do vašeho agenta. Zamčené je to bezpečné, otevřené do internetu ne.
Hermes ověřuje podpis každého požadavku (HMAC), ale port 8644 nikdy nevystavujte přímo do světa.
Webhook patří za firewall nebo za reverzní proxy s HTTPS — a tajný klíč patří do
.env,
ne do gitu.K čemu to je
Agent pak nemusí čekat, až se ho někdo zeptá. Když se ve vaší aplikaci něco stane (nový pull request, zaplacená objednávka, nový článek, chyba v logu), aplikace pošle požadavek a Hermes na něm začne pracovat — a výsledek doručí tam, kam určíte.
| Typické použití | Co agent udělá |
|---|---|
| GitHub: nový pull request | Projde změny, napíše revizi a vloží ji jako komentář k PR |
| Push do hlavní větve | Zkontroluje web, spustí testy, napíše na Telegram, že je hotovo |
| Z vaší aplikace: dokončená platba | Vystaví doklad, pošle e-mail, založí úkol |
| Monitoring: spadlá služba | Podívá se na logy a pošle souhrn, co se stalo |
Zapnutí
# ~/.hermes/.env
WEBHOOK_ENABLED=true
WEBHOOK_PORT=8644 # výchozí
WEBHOOK_SECRET=vas-globalni-tajny-klic
# nebo průvodcem (zapne webhooky, port a globální klíč)
hermes gateway setup
# ověření, že server běží
curl http://localhost:8644/health
# → {"status": "ok", "platform": "webhook"}
Trasy
Každý zdroj událostí má vlastní pojmenovanou trasu. Adresa pro váš systém je pak
http://vas-server:8644/webhooks/<nazev-trasy>.
| Vlastnost | Význam |
|---|---|
events | Které typy událostí brát (např. ["pull_request"]); prázdné = vše |
secret | Povinné. Klíč pro ověření podpisu; bez něj platí globální |
prompt | Zadání pro agenta s hodnotami z události ({pull_request.title}) |
filters | Filtr na obsah — událost, která neprojde, agenta vůbec nevzbudí |
skills | Které skilly má agent pro tuto trasu načíst |
deliver | Kam poslat odpověď: telegram, discord, github_comment, email, log (výchozí)… |
deliver_only | Přeskočí agenta — zpráva se jen přepošle (nulové náklady na model) |
cron_job | Místo nového sezení spustí existující pravidelnou úlohu |
coalesce | Slije rychlé události o téže věci do jednoho běhu (např. 5 commitů v PR) |
Příklad: revize pull requestu
platforms:
webhook:
enabled: true
extra:
port: 8644
secret: "globalni-zalozni-klic"
routes:
github-pr:
events: ["pull_request"]
secret: "klic-pro-github"
prompt: |
Zkontroluj tento pull request:
Repozitář: {repository.full_name}
PR #{number}: {pull_request.title}
Autor: {pull_request.user.login}
URL: {pull_request.html_url}
Diff: {pull_request.diff_url}
Akce: {action}
skills: ["github-code-review"]
deliver: "github_comment"
deliver_extra:
repo: "{repository.full_name}"
pr_number: "{number}"
deploy-notify:
events: ["push"]
secret: "klic-pro-deploy"
prompt: "Nový push do {repository.full_name}, větev {ref}: {head_commit.message}"
filters:
- field: "ref"
equals: "refs/heads/main"
deliver: "telegram"
Trasu můžete založit i příkazem
hermes webhook subscribe <nazev> # vytvoří trasu za běhu
hermes webhook subscribe <nazev> --route-profile coder # pro konkrétní profil
Trasu založenou příkazem nejde povýšit na vyšší oprávnění — nástroje (toolsets)
se u tras mění jen ručně v config.yaml. Je to schválně: kdyby to uměl agent sám, mohl by
si webhookem přidělit víc, než má.
Bezpečnost: podepsané neznamená důvěryhodné
| Pravidlo | Proč |
|---|---|
| Port 8644 nikdy přímo do internetu | Za reverzní proxy s HTTPS, nebo jen na localhost/VPN |
INSECURE_NO_AUTH jen na zkoušku | Vypíná ověření podpisu — na produkci nikdy |
| Vlastní klíč pro každou trasu | Když unikne klíč z GitHubu, ostatní trasy zůstanou zavřené |
| Obsah události je cizí text | Popis PR nebo zpráva od uživatele může obsahovat pokyn („ignoruj pravidla a…“). Agent se jím nesmí řídit |
Filtry a events co nejtěsnější | Méně probuzení = méně nákladů a menší plocha pro zneužití |
Na co si dát pozor
| Situace | Co s tím |
|---|---|
Webhook nefunguje, ale /health odpovídá | Nejspíš nesedí podpis (jiný klíč) nebo událost neprošla events/filters — vrací se 200 s "ignored" |
| Port 8644 je obsazený | Něco jiného ho používá; změňte WEBHOOK_PORT a upravte adresu u zdroje |
| Agent na událost nereaguje po restartu | Webhooky obsluhuje brána — musí běžet (hermes gateway status) |
| Příliš mnoho běhů z jednoho PR | Přidejte coalesce (klíč např. pull_request.number) |
| Chcete jen přeposlat zprávu | deliver_only: true — bez agenta a bez nákladů na model |