Webhooks — Cổng Sự Kiện Vạn Năng | Easy Understand Hermes Agent

Webhooks — Cổng Sự Kiện Vạn Năng

Hãy tưởng tượng thế này: một developer mở pull request trên GitHub, và chỉ trong vài giây, AI agent của bạn đã review code và đăng bình luận. Hoặc một giao dịch thanh toán thất bại trên Stripe, và agent của bạn tự động thông báo cho team qua Telegram. Đó chính là sức mạnh của webhooks — chúng cho phép các dịch vụ bên ngoài “gõ cửa” agent của bạn và nói: “Này, có chuyện vừa xảy ra, xử lý giúp tôi.”

Webhooks Là Gì?

Webhooks giống như chuông cửa cho ứng dụng của bạn. Thay vì liên tục kiểm tra xem có gì thay đổi không (polling), bạn chỉ cần ngồi chờ chuông reo. Khi GitHub, GitLab, JIRA, Stripe, hay bất kỳ dịch vụ nào khác gửi một HTTP POST request đến webhook endpoint của bạn, Hermes agent sẽ thức dậy, xử lý sự kiện, và hành động.

Phần tuyệt nhất? Agent của bạn có thể phản hồi theo nhiều cách — đăng bình luận trên PR, gửi tin nhắn đến Telegram hoặc Discord, hoặc đơn giản là ghi log kết quả để xem lại sau.

Bắt Đầu Nhanh

Bắt đầu thì đơn giản đến bất ngờ:

Bật webhook adapter qua hermes gateway setup hoặc biến môi trường
Định nghĩa routes trong config.yaml hoặc tạo động bằng hermes webhook subscribe
Trỏ dịch vụ của bạn đến http://your-server:8644/webhooks/<route-name>

Chỉ vậy thôi. Agent của bạn đã sẵn sàng trực chiến.

Thiết Lập Gateway

Bạn có hai cách để bật webhooks, chọn cách nào thoải mái nhất.

Tùy chọn 1: Trình Hướng Dẫn Thiết Lập

hermes gateway setup

Làm theo hướng dẫn để bật webhooks, chọn port, và đặt HMAC secret toàn cục. Trình hướng dẫn sẽ lo hết mấy phần cấu hình nhàm chán cho bạn.

Tùy chọn 2: Biến Môi Trường

Thêm những dòng này vào ~/.hermes/.env:

WEBHOOK_ENABLED=true
WEBHOOK_PORT=8644        # mặc định
WEBHOOK_SECRET=your-global-secret

Khi gateway đã chạy, kiểm tra xem nó còn sống không:

curl http://localhost:8644/health

Bạn sẽ thấy:

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

Cấu Hình Routes

Routes là trái tim của việc xử lý webhook. Mỗi route cho agent biết cách xử lý sự kiện từ một nguồn cụ thể. Hãy nghĩ về chúng như những chỉ dẫn cá nhân hóa cho từng loại khách ghé thăm.

Đây là những gì bạn có thể cấu hình cho mỗi route:

Thuộc tính	Chức năng
`events`	Loại sự kiện nào được chấp nhận (ví dụ: `["pull_request"]`). Để trống để chấp nhận mọi thứ.
`secret`	HMAC secret để xác thực chữ ký. Chỉ dùng `"INSECURE_NO_AUTH"` khi test.
`profile`	Profile nào có thể thực thi route này (hữu ích với multiplexing).
`prompt`	Chuỗi template dùng dot-notation như `{pull_request.title}`. Bỏ trống để dump toàn bộ JSON payload.
`filters`	Điều kiện khai báo để bỏ qua payload không mong muốn trước khi agent chạy.
`script`	Script lọc/biến đổi có thể sửa payload trước khi tạo template.
`skills`	Những skill nào được tải cho lần chạy agent này.
`toolsets`	Những công cụ nào agent có thể dùng (thay thế webhook toolset mặc định).
`deliver`	Nơi gửi phản hồi: `github_comment`, `telegram`, `discord`, `slack`, `log`, và nhiều hơn nữa.
`deliver_extra`	Chi tiết giao nhận bổ sung như tên repo hoặc chat ID.
`deliver_only`	Bỏ qua agent hoàn toàn và gửi prompt đã render nguyên văn. Tốn 0 chi phí LLM!

Ví Dụ Thực Tế

Hãy xem một thiết lập thực tế. Đây là route review 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 pull request này:
            Repository: {repository.full_name}
            PR #{number}: {pull_request.title}
            Tác giả: {pull_request.user.login}
            URL: {pull_request.html_url}
            Diff URL: {pull_request.diff_url}
            Hành động: {action}
          skills: ["github-code-review"]
          deliver: "github_comment"
          deliver_extra:
            repo: "{repository.full_name}"
            pr_number: "{number}"

Và đây là route gửi thông báo Telegram chỉ khi ai đó push lên nhánh main:

        deploy-notify:
          events: ["push"]
          secret: "deploy-secret"
          prompt: "Push mới đến {repository.full_name} nhánh {ref}: {head_commit.message}"
          filters:
            - field: "ref"
              equals: "refs/heads/main"
          deliver: "telegram"

Lọc Thông Minh

Tính năng filters cực kỳ hữu ích. Các nhà cung cấp thường gửi một loạt sự kiện, nhưng bạn chỉ quan tâm đến vài cái. Filters giúp bạn bỏ qua nhiễu trước khi agent thức dậy. Payload không khớp sẽ nhận phản hồi lịch sự {"status":"ignored","reason":"filter"} với HTTP 200 — không tốn compute, không gọi LLM thừa thãi.

Chế Độ Giao Nhận Trực Tiếp

Đây là một mẹo hay: đặt deliver_only: true và agent của bạn sẽ không bao giờ chạy. Prompt template đã render sẽ trở thành tin nhắn được gửi đi nguyên văn. Điều này có nghĩa là giao nhận trong chưa đầy một giây với chi phí LLM bằng 0. Hoàn hảo cho các thông báo đơn giản không cần suy luận AI.

Lưu Ý Bảo Mật

Hãy nhớ: được xác thực không có nghĩa là đáng tin cậy. Các trường payload từ webhooks là dữ liệu không đáng tin. Luôn kiểm tra và làm sạch mọi thứ bạn dùng trong prompts hoặc templates. Agent của bạn nên coi nội dung webhook như input từ người dùng — với sự hoài nghi lành mạnh.

Kết Luận

Webhooks biến Hermes agent của bạn thành một trợ lý phản hồi nhanh nhạy, tương tác với thế giới theo thời gian thực. Dù bạn đang tự động hóa code review, gửi thông báo triển khai, hay xây dựng các quy trình phức tạp dựa trên sự kiện, webhook adapter giúp tất cả trở nên khả thi chỉ với vài dòng YAML.