Webhooks — Pintu Masuk Universal untuk Event | Easy Understand Hermes Agent

Webhooks — Pintu Masuk Universal untuk Event

Bayangkan ini: seorang developer membuka pull request di GitHub, dan dalam hitungan detik, agen AI kamu sudah meninjau kode tersebut dan memberikan komentar. Atau pembayaran gagal di Stripe, dan agen kamu otomatis memberi tahu tim kamu di Telegram. Itulah keajaiban webhooks — mereka memungkinkan layanan eksternal mengetuk pintu agen kamu dan berkata, “Hei, sesuatu baru saja terjadi, tolong tangani.”

Apa Itu Webhooks?

Webhooks itu seperti bel pintu untuk aplikasi kamu. Alih-alih terus-menerus memeriksa apakah ada yang berubah (polling), kamu cukup menunggu bel pintu berbunyi. Ketika GitHub, GitLab, JIRA, Stripe, atau layanan lainnya mengirimkan permintaan HTTP POST ke endpoint webhook kamu, agen Hermes kamu terbangun, memproses event tersebut, dan mengambil tindakan.

Bagian terbaiknya? Agen kamu bisa merespons dengan berbagai cara — memberikan komentar di PR, mengirim pesan ke Telegram atau Discord, atau sekadar mencatat hasilnya untuk ditinjau nanti.

Memulai dengan Cepat

Memulainya sangatlah mudah:

Aktifkan adapter webhook melalui hermes gateway setup atau variabel lingkungan
Definisikan route di config.yaml atau buat secara dinamis dengan hermes webhook subscribe
Arahkan layanan kamu ke http://server-anda:8644/webhooks/<nama-route>

Selesai. Agen kamu sekarang siap siaga.

Menyiapkan Gateway

Ada dua cara untuk mengaktifkan webhooks, pilih yang paling nyaman buat kamu.

Opsi 1: Wizard Setup

hermes gateway setup

Ikuti petunjuknya untuk mengaktifkan webhooks, pilih port, dan atur HMAC secret global. Wizard akan menangani semua konfigurasi yang membosankan untuk kamu.

Opsi 2: Variabel Lingkungan

Tambahkan baris-baris ini ke ~/.hermes/.env:

WEBHOOK_ENABLED=true
WEBHOOK_PORT=8644        # default
WEBHOOK_SECRET=global-secret-anda

Setelah gateway berjalan, verifikasi bahwa ia hidup:

curl http://localhost:8644/health

Kamu akan melihat:

{"status": "ok", "platform": "webhook"}

Mengonfigurasi Route

Route adalah jantung dari penanganan webhook. Setiap route memberi tahu agen kamu cara menangani event dari sumber tertentu. Anggap saja mereka sebagai instruksi yang dipersonalisasi untuk berbagai jenis pengunjung.

Inilah yang bisa kamu konfigurasi per route:

Properti	Fungsinya
`events`	Jenis event apa yang diterima (misalnya, `["pull_request"]`). Biarkan kosong untuk menerima semuanya.
`secret`	HMAC secret untuk validasi tanda tangan. Gunakan `"INSECURE_NO_AUTH"` hanya untuk pengujian.
`profile`	Profil mana yang bisa mengeksekusi route ini (berguna dengan multiplexing).
`prompt`	String template menggunakan notasi titik seperti `{pull_request.title}`. Hapus untuk membuang payload JSON lengkap.
`filters`	Kondisi deklaratif untuk mengabaikan payload yang tidak diinginkan sebelum agen dijalankan.
`script`	Skrip filter/transformasi yang bisa memodifikasi payload sebelum templating.
`skills`	Skill mana yang akan dimuat untuk eksekusi agen ini.
`toolsets`	Tool apa saja yang bisa digunakan agen (menggantikan toolset webhook default).
`deliver`	Ke mana respons dikirim: `github_comment`, `telegram`, `discord`, `slack`, `log`, dan lainnya.
`deliver_extra`	Detail pengiriman tambahan seperti nama repo atau ID chat.
`deliver_only`	Lewati agen sepenuhnya dan kirim prompt yang sudah dirender apa adanya. Biaya LLM nol!

Contoh Dunia Nyata

Mari kita lihat pengaturan yang praktis. Berikut route yang meninjau pull request:

platforms:
  webhook:
    enabled: true
    extra:
      port: 8644
      secret: "global-fallback-secret"
      routes:
        github-pr:
          events: ["pull_request"]
          secret: "github-webhook-secret"
          prompt: |
            Tinjau pull request ini:
            Repository: {repository.full_name}
            PR #{number}: {pull_request.title}
            Penulis: {pull_request.user.login}
            URL: {pull_request.html_url}
            URL Diff: {pull_request.diff_url}
            Aksi: {action}
          skills: ["github-code-review"]
          deliver: "github_comment"
          deliver_extra:
            repo: "{repository.full_name}"
            pr_number: "{number}"

Dan berikut route yang mengirim notifikasi Telegram hanya ketika seseorang melakukan push ke branch utama:

        deploy-notify:
          events: ["push"]
          secret: "deploy-secret"
          prompt: "Push baru ke {repository.full_name} cabang {ref}: {head_commit.message}"
          filters:
            - field: "ref"
              equals: "refs/heads/main"
          deliver: "telegram"

Penyaringan Cerdas

Fitur filters sangat berguna. Penyedia layanan sering mengirim banjir event, tapi kamu hanya peduli pada beberapa saja. Filter memungkinkan kamu mengabaikan kebisingan sebelum agen kamu bahkan terbangun. Payload yang tidak cocok akan mendapat respons sopan {"status":"ignored","reason":"filter"} dengan HTTP 200 — tidak ada komputasi yang terbuang, tidak ada panggilan LLM yang tidak perlu.

Mode Pengiriman Langsung

Ini trik yang cerdas: atur deliver_only: true dan agen kamu tidak akan berjalan sama sekali. Template prompt yang sudah dirender menjadi pesan literal yang dikirim. Ini berarti pengiriman dalam waktu kurang dari satu detik dengan biaya LLM nol. Sempurna untuk notifikasi sederhana yang tidak membutuhkan penalaran AI.

Catatan Keamanan

Ingat: terautentikasi tidak berarti tepercaya. Field payload dari webhooks adalah data yang tidak tepercaya. Selalu validasi dan bersihkan apa pun yang kamu gunakan dalam prompt atau template. Agen kamu harus memperlakukan konten webhook seperti input pengguna — dengan skeptisisme yang sehat.

Intinya

Webhooks mengubah agen Hermes kamu menjadi asisten yang responsif yang bereaksi terhadap dunia secara real-time. Baik kamu mengotomatiskan tinjauan kode, mengirim notifikasi deployment, atau membangun alur kerja berbasis event yang kompleks, adapter webhook membuat semuanya mungkin hanya dengan beberapa baris YAML.