Hermes Gateway + Webhook: Bikin Automation Event-Driven

Panduan lengkap membangun event-driven automation dengan Hermes Agent Gateway dan webhook subscription, dari endpoint setup, integrasi cron/trigger, hingga notifikasi real-time via Telegram/Slack.

Hermes Agent bukan cuma bot atau skill. Dia bisa jadi gateway ke sistem eksternal, webhook endpoint yang ngirim event ke Telegram, Slack, atau cron job lain. Setup-nya simpel, tapi kalau dipakai dengan benar, bisa bikin automation yang really event-driven.

Di artikel ini, kita bahas konfigurasi gateway, integrasi webhook dengan cron/trigger, use case nyata (bot Telegram/Slack, sync data, notifikasi real-time), kode contoh (JSON config + Python handler), dan troubleshooting + best practices.

1. Kenapa Hermes Gateway + Webhook?

Kalau lo pakai Hermes Agent untuk automation, biasanya jalan di dua pola:

• Cron job → trigger skill/agent → output ke Slack/Telegram
• Manual trigger → skill/agent → output ke Slack/Telegram

Tapi kalau lo butuh event-driven, misalnya: saat ada event tertentu (misalnya GitHub webhook, cron job sukses/gagal, atau sinyal dari external service), langsung ada notifikasi real-time, maka webhook adalah pattern yang tepat.

Hermes Agent Gateway menyediakan:

• HTTP endpoint yang bisa di-call dari sistem eksternal
• Webhook subscription yang bisa di-trigger dari cron job, GitHub, atau event lain
• Integrasi langsung ke bot Telegram dan Slack

Dengan kombinasi ini, lo bisa bikin pipeline event-driven yang scalable dan maintainable.

2. Konfigurasi Gateway Hermes Agent + Endpoint Webhook

Langkah pertama: setup Hermes Agent gateway dengan endpoint webhook.

2.1. Setup Gateway di Hermes Agent

Hermes Agent gateway di-configure via config.yaml. Pastikan lo sudah punya endpoint Hermes Agent yang aktif (misalnya di VPS atau cloud).

Contoh config.yaml:

gateway:
  enabled: true
  port: 8080
  host: 0.0.0.0

webhooks:
  enabled: true
  secret: "rahasia-aman"  # ganti dengan secret yang kuat
  max_retries: 3
  timeout: 30s

Setelah config di-save, restart Hermes Agent:

hermes restart

2.2. Buat Webhook Subscription

Webhook subscription di-define di skills/ atau plugins/, lebih enak kalau pakai custom skill khusus webhook.

Contoh skill: hermes-gateway-webhook-handler.

Struktur:

skills/hermes-gateway-webhook-handler/
├── SKILL.md
├── handler.py
└── templates/
    └── webhook_payload.json

Di SKILL.md:

---
name: hermes-gateway-webhook-handler
category: automation
---

# Hermes Gateway Webhook Handler

Skill ini menyediakan endpoint webhook untuk event-driven automation.

## Trigger

- Webhook call dari Hermes Agent Gateway
- Event: cron job, GitHub webhook, atau sinyal eksternal

## Actions

- `webhook_trigger`: Terima payload webhook, eksekusi logic, kirim notifikasi ke Telegram/Slack

Di handler.py:

import os
import json
import logging
from typing import Dict, Any

logger = logging.getLogger(__name__)

def handle_webhook(payload: Dict[str, Any]) -> Dict[str, Any]:
    """
    Handle webhook payload dan kirim notifikasi ke Telegram/Slack.
    """
    event_type = payload.get("event_type", "unknown")
    data = payload.get("data", {})

    logger.info(f"Received webhook: {event_type}, data={data}")

    # Contoh: kirim notifikasi ke Telegram
    if event_type == "cron_success":
        message = f"Cron job sukses: {data.get('job_name')}"
        # kirim ke Telegram via bot
        send_telegram_message(message)

    # Contoh: kirim notifikasi ke Slack
    elif event_type == "cron_failure":
        message = f"Cron job gagal: {data.get('job_name')}"
        send_slack_message(message)

    return {"status": "ok", "event_type": event_type}

def send_telegram_message(text: str) -> None:
    """
    Kirim pesan ke Telegram bot.
    """
    bot_token = os.getenv("TELEGRAM_BOT_TOKEN")
    chat_id = os.getenv("TELEGRAM_CHAT_ID")

    if not bot_token or not chat_id:
        logger.warning("TELEGRAM_BOT_TOKEN or TELEGRAM_CHAT_ID not set")
        return

    url = f"https://api.telegram.org/bot{bot_token}/sendMessage"
    payload = {"chat_id": chat_id, "text": text}

    # Implementasi HTTP request (gunakan requests atau httpx)
    # response = requests.post(url, json=payload)
    # response.raise_for_status()
    logger.info(f"Telegram message sent: {text[:50]}...")

def send_slack_message(text: str) -> None:
    """
    Kirim pesan ke Slack webhook.
    """
    webhook_url = os.getenv("SLACK_WEBHOOK_URL")

    if not webhook_url:
        logger.warning("SLACK_WEBHOOK_URL not set")
        return

    payload = {"text": text}

    # Implementasi HTTP request
    # response = requests.post(webhook_url, json=payload)
    # response.raise_for_status()
    logger.info(f"Slack message sent: {text[:50]}...")

2.3. Register Endpoint Webhook

Webhook endpoint di-register di Hermes Agent Gateway config. Di config.yaml:

gateway:
  enabled: true
  port: 8080
  host: 0.0.0.0

webhooks:
  enabled: true
  secret: "rahasia-aman"
  max_retries: 3
  timeout: 30s
  routes:
    - path: /webhook/hermes-gateway
      handler: hermes-gateway-webhook-handler:handle_webhook
      secret: "rahasia-aman"

Setelah config di-save, restart Hermes Agent:

hermes restart

Endpoint webhook sekarang bisa di-access di:

http://<your-domain>:8080/webhook/hermes-gateway

3. Integrasi Webhook dengan Cron/Trigger

Webhook bisa di-trigger dari cron job, GitHub webhook, atau event lain. Di sini kita bahas dua use case utama: cron job dan GitHub webhook.

3.1. Webhook dari Cron Job

Cron job bisa memanggil webhook endpoint dengan payload yang sesuai. Contoh cron job di Hermes Agent:

cron:
  enabled: true
  jobs:
    - name: daily_summary
      schedule: "0 9 * * *"  # Setiap hari pukul 09:00
      action: cron_daily_summary
      notify_webhook: true
      webhook_url: http://<your-domain>:8080/webhook/hermes-gateway
      webhook_secret: "rahasia-aman"

Di SKILL.md untuk cron_daily_summary:

---
name: cron_daily_summary
category: cron
---

# Cron Job: Daily Summary

Trigger setiap hari pukul 09:00, kirim summary ke webhook.

## Actions

- `cron_daily_summary`: Generate daily summary, kirim ke webhook.

Di handler.py:

def cron_daily_summary() -> Dict[str, Any]:
    """
    Generate daily summary dan kirim ke webhook.
    """
    summary = {
        "event_type": "cron_success",
        "data": {
            "job_name": "daily_summary",
            "timestamp": datetime.now().isoformat(),
            "summary": "Daily summary berisi aktivitas hari ini"
        }
    }

    # Simpan summary ke file atau database
    save_summary(summary)

    return summary

Kalau webhook gagal, Hermes Agent akan retry sesuai max_retries dan timeout di config.

3.2. Webhook dari GitHub Event

Kalau lo pakai GitHub untuk deployment atau CI/CD, GitHub webhook bisa trigger webhook Hermes Agent.

Di GitHub repository:

1. Settings → Webhooks → Add webhook
2. Payload URL: http://<your-domain>:8080/webhook/hermes-gateway
3. Secret: rahasia-aman (sesuai config Hermes)
4. Events: pilih event yang lo mau (misalnya push, pull_request, release)

Di handler.py:

def handle_github_webhook(payload: Dict[str, Any]) -> Dict[str, Any]:
    """
    Handle GitHub webhook dan kirim notifikasi ke Telegram/Slack.
    """
    event_type = payload.get("zen", "unknown")
    data = payload.get("repository", {})

    logger.info(f"Received GitHub webhook: {event_type}, repo={data.get('name')}")

    if event_type == "push":
        message = f"Push ke repository: {data.get('name')} - {payload.get('ref')}"
        send_telegram_message(message)
        send_slack_message(message)

    return {"status": "ok", "event_type": event_type}

4. Use Case Nyata: Bot Telegram/Slack Automation

4.1. Notifikasi Real-Time Cron Job

Cron job sukses/gagal bisa langsung notifikasi ke Telegram/Slack via webhook.

Contoh payload:

{
  "event_type": "cron_success",
  "data": {
    "job_name": "daily_summary",
    "timestamp": "2026-11-10T09:00:00+07:00",
    "summary": "Daily summary berisi aktivitas hari ini"
  }
}

Di handler.py:

if event_type == "cron_success":
    message = f"✅ Cron job sukses: {data.get('job_name')}\n"
    message += f"⏰ Timestamp: {data.get('timestamp')}\n"
    message += f"📋 Summary: {data.get('summary')}"

    send_telegram_message(message)
    send_slack_message(message)

Hasil di Telegram:

✅ Cron job sukses: daily_summary
⏰ Timestamp: 2026-11-10T09:00:00+07:00
📋 Summary: Daily summary berisi aktivitas hari ini

4.2. Sync Data ke Telegram/Slack

Webhook juga bisa dipakai untuk sync data ke Telegram/Slack. Contoh: saat ada data baru di database, webhook trigger notifikasi ke Telegram.

Contoh payload:

{
  "event_type": "data_new",
  "data": {
    "table": "users",
    "record_id": 123,
    "fields": {
      "name": "John Doe",
      "email": "[email protected]"
    }
  }
}

Di handler.py:

if event_type == "data_new":
    message = f"🆕 Data baru di tabel {data.get('table')}:\n"
    message += f"ID: {data.get('record_id')}\n"
    message += f"Fields: {json.dumps(data.get('fields'), ensure_ascii=False)}"

    send_telegram_message(message)
    send_slack_message(message)

4.3. Alert Real-Time

Webhook bisa dipakai untuk alert real-time, misalnya: saat ada error di log atau saat sistem mendeteksi anomali.

Contoh payload:

{
  "event_type": "alert_critical",
  "data": {
    "alert_type": "high_memory_usage",
    "host": "server-01",
    "value": "85%",
    "timestamp": "2026-11-10T10:30:00+07:00"
  }
}

Di handler.py:

if event_type == "alert_critical":
    message = f"⚠️ Alert kritis: {data.get('alert_type')}\n"
    message += f"Host: {data.get('host')}\n"
    message += f"Value: {data.get('value')}\n"
    message += f"Timestamp: {data.get('timestamp')}"

    send_telegram_message(message)
    send_slack_message(message)

Hasil di Slack:

⚠️ Alert kritis: high_memory_usage
Host: server-01
Value: 85%
Timestamp: 2026-11-10T10:30:00+07:00

5. Kode Contoh (JSON Config + Python Handler)

5.1. JSON Config Webhook

Contoh webhook_payload.json:

{
  "event_type": "cron_success",
  "data": {
    "job_name": "daily_summary",
    "timestamp": "2026-11-10T09:00:00+07:00",
    "summary": "Daily summary berisi aktivitas hari ini"
  }
}

5.2. Python Handler Webhook

Contoh handler.py lengkap:

import os
import json
import logging
from datetime import datetime
from typing import Dict, Any

logger = logging.getLogger(__name__)

def handle_webhook(payload: Dict[str, Any]) -> Dict[str, Any]:
    """
    Handle webhook payload dan kirim notifikasi ke Telegram/Slack.
    """
    event_type = payload.get("event_type", "unknown")
    data = payload.get("data", {})

    logger.info(f"Received webhook: {event_type}, data={data}")

    # Cron job success
    if event_type == "cron_success":
        message = f"✅ Cron job sukses: {data.get('job_name')}\n"
        message += f"⏰ Timestamp: {data.get('timestamp')}\n"
        message += f"📋 Summary: {data.get('summary')}"
        send_telegram_message(message)
        send_slack_message(message)

    # Cron job failure
    elif event_type == "cron_failure":
        message = f"❌ Cron job gagal: {data.get('job_name')}\n"
        message += f"⏰ Timestamp: {data.get('timestamp')}\n"
        message += f"Error: {data.get('error')}"
        send_telegram_message(message)
        send_slack_message(message)

    # GitHub push
    elif event_type == "push":
        repo = data.get("repository", {})
        message = f"🚀 Push ke repository: {repo.get('name')}\n"
        message += f"Branch: {data.get('ref')}\n"
        message += f"Commit: {data.get('head_commit', {}).get('id')[:7]}"
        send_telegram_message(message)
        send_slack_message(message)

    # Data baru
    elif event_type == "data_new":
        table = data.get("table", "unknown")
        record_id = data.get("record_id", "unknown")
        fields = data.get("fields", {})
        message = f"🆕 Data baru di tabel {table}:\n"
        message += f"ID: {record_id}\n"
        message += f"Fields: {json.dumps(fields, ensure_ascii=False)}"
        send_telegram_message(message)
        send_slack_message(message)

    # Alert kritis
    elif event_type == "alert_critical":
        alert_type = data.get("alert_type", "unknown")
        host = data.get("host", "unknown")
        value = data.get("value", "unknown")
        timestamp = data.get("timestamp", "unknown")
        message = f"⚠️ Alert kritis: {alert_type}\n"
        message += f"Host: {host}\n"
        message += f"Value: {value}\n"
        message += f"Timestamp: {timestamp}"
        send_telegram_message(message)
        send_slack_message(message)

    return {"status": "ok", "event_type": event_type}

def send_telegram_message(text: str) -> None:
    """
    Kirim pesan ke Telegram bot.
    """
    bot_token = os.getenv("TELEGRAM_BOT_TOKEN")
    chat_id = os.getenv("TELEGRAM_CHAT_ID")

    if not bot_token or not chat_id:
        logger.warning("TELEGRAM_BOT_TOKEN or TELEGRAM_CHAT_ID not set")
        return

    url = f"https://api.telegram.org/bot{bot_token}/sendMessage"
    payload = {"chat_id": chat_id, "text": text}

    # Implementasi HTTP request (gunakan requests atau httpx)
    # response = requests.post(url, json=payload)
    # response.raise_for_status()
    logger.info(f"Telegram message sent: {text[:50]}...")

def send_slack_message(text: str) -> None:
    """
    Kirim pesan ke Slack webhook.
    """
    webhook_url = os.getenv("SLACK_WEBHOOK_URL")

    if not webhook_url:
        logger.warning("SLACK_WEBHOOK_URL not set")
        return

    payload = {"text": text}

    # Implementasi HTTP request
    # response = requests.post(webhook_url, json=payload)
    # response.raise_for_status()
    logger.info(f"Slack message sent: {text[:50]}...")

6. Troubleshooting + Best Practices

6.1. Troubleshooting Webhook

6.1.1. Webhook Gagal di-Trigger

Cek:

• Endpoint URL benar?
• Secret di webhook subscription sama dengan secret di config?
• Hermes Agent gateway running?

Test endpoint dengan curl:

curl -X POST http://<your-domain>:8080/webhook/hermes-gateway \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: rahasia-aman" \
  -d '{"event_type": "test", "data": {"message": "test"}}'

6.1.2. Webhook Gagal di-Receive

Cek:

• Log Hermes Agent (hermes logs)
• Log handler Python (hermes logs --skill hermes-gateway-webhook-handler)
• Network connectivity (firewall, DNS)

6.1.3. Webhook Retry Gagal

Cek:

• max_retries dan timeout di config
• Error log di Hermes Agent
• Secret tidak valid

6.2. Best Practices

6.2.1. Gunakan Secret yang Kuat

Secret webhook harus kuat dan unik untuk setiap endpoint. Gunakan environment variable atau secrets manager.

6.2.2. Validasi Payload

Selalu validasi payload sebelum diproses:

def handle_webhook(payload: Dict[str, Any]) -> Dict[str, Any]:
    if not isinstance(payload, dict):
        return {"status": "error", "message": "Invalid payload"}

    event_type = payload.get("event_type")
    if not event_type:
        return {"status": "error", "message": "Missing event_type"}

    # lanjutkan proses...

6.2.3. Limit Rate dan Retry

Gunakan max_retries dan timeout yang tepat. Jangan set retry terlalu banyak, karena bisa bikin spam log.

6.2.4. Logging yang Jelas

Log event_type, timestamp, dan data penting untuk debugging.

6.2.5. Separasi Event Type

Jangan sembarangan kirim semua event ke Telegram/Slack. Pisahkan event type:

• Critical: alert kritis → notifikasi langsung
• Warning: cron failure → notifikasi
• Info: cron success → bisa skip atau log saja

7. Penutup

Hermes Agent Gateway + Webhook adalah pattern yang powerful untuk event-driven automation. Dengan endpoint webhook, lo bisa:

• Trigger automation dari cron job, GitHub, atau event eksternal
• Kirim notifikasi real-time ke Telegram/Slack
• Sync data secara real-time
• Alert kritis secara langsung

Setup-nya simpel, tapi kalau dipakai dengan benar, bisa bikin automation yang scalable dan maintainable.

Kalau lo butuh contoh lain (misalnya integrasi dengan database, queue, atau service lain), tinggal expand handler Python dan tambahkan event type sesuai kebutuhan.

CTA

Kalau lo sudah setup Hermes Agent Gateway + Webhook, bagaimana lo pakainya? Share di Telegram atau Slack, atau diskusikan di GitHub issue.

Kalau lo butuh panduan lebih lanjut, bisa cari di dokumentasi Hermes Agent: https://hermes-agent.nousresearch.com/docs

FAQ

Q1: Apakah webhook bisa dipakai untuk cron job yang berjalan setiap menit?

Ya, webhook bisa dipakai untuk cron job yang berjalan setiap menit atau bahkan lebih sering. Pastikan lo validasi payload dan limit rate agar tidak spam notifikasi.

Q2: Apakah webhook bisa di-trigger dari external service selain GitHub?

Ya, webhook bisa di-trigger dari external service apa saja yang bisa mengirim HTTP POST ke endpoint Hermes Agent Gateway. Contoh: cron job di server lain, API service, atau even dari platform lain.

Q3: Bagaimana cara mengamankan webhook dari abuse?

Gunakan secret yang kuat, validasi payload, dan limit rate. Juga bisa gunakan IP whitelist jika endpoint hanya diakses dari service tertentu.