Webhooks — ประตูรับเหตุการณ์สากล

ลองนึกภาพดู: นักพัฒนาคนหนึ่งเปิด pull request บน GitHub และภายในไม่กี่วินาที AI agent ของคุณก็ตรวจสอบโค้ดและโพสต์คอมเมนต์เรียบร้อยแล้ว หรือการชำระเงินล้มเหลวบน Stripe แล้ว agent ของคุณแจ้งเตือนทีมของคุณบน Telegram โดยอัตโนมัติ นี่คือความมหัศจรรย์ของ webhooks — มันให้บริการภายนอกมาเคาะประตูบ้าน agent ของคุณแล้วบอกว่า “เฮ้ มีอะไรเพิ่งเกิดขึ้น ช่วยจัดการให้หน่อย”

Webhooks คืออะไร?

Webhooks ก็เหมือนกริ่งประตูสำหรับแอปพลิเคชันของคุณ แทนที่จะคอยตรวจสอบตลอดเวลาว่ามีอะไรเปลี่ยนแปลงหรือไม่ (polling) คุณก็แค่นั่งรอให้กริ่งดัง เมื่อ GitHub, GitLab, JIRA, Stripe หรือบริการอื่นๆ ส่งคำขอ HTTP POST มาที่ webhook endpoint ของคุณ Hermes agent ของคุณก็จะตื่นขึ้นมา ประมวลผลเหตุการณ์นั้น และลงมือทำ

จุดเด่นที่สุด? Agent ของคุณตอบสนองได้หลายวิธี — โพสต์คอมเมนต์บน PR, ส่งข้อความไปยัง Telegram หรือ Discord, หรือแค่บันทึกผลลัพธ์ไว้ดูทีหลัง

เริ่มต้นใช้งาน

การเริ่มต้นใช้งานง่ายกว่าที่คิด:

เปิดใช้งาน webhook adapter ผ่าน hermes gateway setup หรือ environment variables
กำหนด routes ใน config.yaml หรือสร้างแบบไดนามิกด้วย hermes webhook subscribe
ชี้บริการของคุณ ไปที่ http://your-server:8644/webhooks/<route-name>

แค่นี้เอง Agent ของคุณก็พร้อมทำงานแล้ว

ตั้งค่า Gateway

คุณมีสองวิธีในการเปิดใช้งาน webhooks เลือกวิธีที่ถนัดได้เลย

ตัวเลือกที่ 1: ตัวช่วยติดตั้ง (Setup Wizard)

hermes gateway setup

ทำตามขั้นตอนที่แสดงเพื่อเปิดใช้งาน webhooks เลือกพอร์ต และตั้งค่า HMAC secret ระดับ global ตัวช่วยติดตั้งจะจัดการเรื่องการตั้งค่าที่น่าเบื่อทั้งหมดให้คุณเอง

ตัวเลือกที่ 2: Environment Variables

เพิ่มบรรทัดเหล่านี้ลงใน ~/.hermes/.env:

WEBHOOK_ENABLED=true
WEBHOOK_PORT=8644        # ค่าเริ่มต้น
WEBHOOK_SECRET=your-global-secret

เมื่อ gateway ทำงานแล้ว ลองตรวจสอบว่ามันยังมีชีวิตอยู่:

curl http://localhost:8644/health

คุณควรเห็น:

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

กำหนดค่า Routes

Routes คือหัวใจของการจัดการ webhooks แต่ละ route บอก agent ของคุณว่าต้องจัดการกับเหตุการณ์จากแหล่งใดแหล่งหนึ่งอย่างไร นึกภาพว่ามันเป็นคำแนะนำเฉพาะบุคคลสำหรับผู้มาเยือนแต่ละประเภท

นี่คือสิ่งที่คุณกำหนดค่าได้ในแต่ละ route:

คุณสมบัติ	หน้าที่
`events`	ระบุประเภทเหตุการณ์ที่จะรับ (เช่น `["pull_request"]`) เว้นว่างไว้เพื่อรับทุกอย่าง
`secret`	HMAC secret สำหรับตรวจสอบลายเซ็น ใช้ `"INSECURE_NO_AUTH"` เฉพาะตอนทดสอบเท่านั้น
`profile`	ระบุว่า profile ไหนสามารถ execute route นี้ได้ (มีประโยชน์กับ multiplexing)
`prompt`	เทมเพลตสตริงแบบ dot-notation เช่น `{pull_request.title}` ละไว้เพื่อ dump JSON payload ทั้งหมด
`filters`	เงื่อนไขแบบ declarative เพื่อกรอง payload ที่ไม่ต้องการก่อนที่ agent จะทำงาน
`script`	สคริปต์กรอง/แปลงค่าที่สามารถแก้ไข payload ก่อนทำ templating
`skills`	ระบุ skills ที่จะโหลดสำหรับการทำงานของ agent ในครั้งนี้
`toolsets`	ระบุ tools ที่ agent ใช้ได้ (แทนที่ webhook toolset เริ่มต้น)
`deliver`	ระบุตำแหน่งที่จะส่งคำตอบ: `github_comment`, `telegram`, `discord`, `slack`, `log` และอื่นๆ
`deliver_extra`	รายละเอียดเพิ่มเติมสำหรับการส่ง เช่น ชื่อ repo หรือ chat ID
`deliver_only`	ข้าม agent ไปเลยแล้วส่ง prompt ที่ render แล้วตรงๆ ไม่มีค่าใช้จ่าย LLM เลย!

ตัวอย่างการใช้งานจริง

มาดูการตั้งค่าที่ใช้งานได้จริงกัน นี่คือ route ที่ใช้ตรวจสอบ pull requests:

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

และนี่คือ route ที่ส่งการแจ้งเตือนทาง Telegram เฉพาะเมื่อมีคน push ไปที่ main branch:

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

การกรองอัจฉริยะ

ฟีเจอร์ filters มีประโยชน์มาก โดยปกติผู้ให้บริการมักส่งเหตุการณ์มาเป็นชุด แต่คุณอาจสนใจแค่ไม่กี่อย่าง Filters ช่วยให้คุณไม่ต้องสนใจสัญญาณรบกวนก่อนที่ agent จะตื่นขึ้นมา payload ที่ไม่ตรงเงื่อนไขจะได้รับการตอบกลับอย่างสุภาพว่า {"status":"ignored","reason":"filter"} พร้อม HTTP 200 — ไม่มีการคำนวณที่สูญเปล่า ไม่มีการเรียก LLM ที่ไม่จำเป็น

โหมดส่งตรง (Direct Delivery Mode)

นี่คือเคล็ดลับสุดเจ๋ง: ตั้งค่า deliver_only: true แล้ว agent ของคุณจะไม่ทำงานเลย เทมเพลต prompt ที่ render แล้วจะกลายเป็นข้อความที่ถูกส่งออกไปตรงๆ ซึ่งหมายถึงการส่งที่ไวระดับต่ำกว่าวินาทีโดยไม่มีค่าใช้จ่าย LLM เลย เหมาะสำหรับการแจ้งเตือนง่ายๆ ที่ไม่ต้องใช้การคิดวิเคราะห์ของ AI

หมายเหตุด้านความปลอดภัย

อย่าลืม: การยืนยันตัวตนไม่ได้หมายความว่าเชื่อถือได้ ฟิลด์ต่างๆ ใน payload จาก webhooks คือข้อมูลที่ไม่น่าเชื่อถือ ต้องตรวจสอบและทำความสะอาดข้อมูลทุกอย่างที่คุณใช้ใน prompts หรือ templates เสมอ Agent ของคุณควรมองเนื้อหา webhook เหมือนกับ input จากผู้ใช้ — ด้วยความระแวงอย่างมีเหตุผล

สรุป

Webhooks เปลี่ยน Hermes agent ของคุณให้เป็นผู้ช่วยที่ตอบสนองต่อโลกแบบเรียลไทม์ ไม่ว่าคุณจะต้องการอัตโนมัติการตรวจสอบโค้ด ส่งการแจ้งเตือนการ deploy หรือสร้างเวิร์กโฟลว์ที่ขับเคลื่อนด้วยเหตุการณ์ที่ซับซ้อน webhook adapter ทำให้ทั้งหมดนี้เป็นไปได้ด้วย YAML แค่ไม่กี่บรรทัด