Webhook

Nhận sự kiện từ các dịch vụ bên ngoài (GitHub, GitLab, JIRA, Stripe, v.v.) và kích hoạt tác nhân Hermes tự động chạy. Bộ điều hợp webhook chạy máy chủ HTTP chấp nhận các yêu cầu POST, xác thực chữ ký HMAC, chuyển tải trọng thành lời nhắc của tổng đài viên và định tuyến phản hồi trở lại nguồn hoặc tới nền tảng được định cấu hình khác.

Đại lý xử lý sự kiện và có thể phản hồi bằng cách đăng nhận xét về PR, gửi tin nhắn tới Telegram/Discord hoặc ghi lại kết quả.

Bắt đầu nhanh

Kích hoạt thông qua hermes gateway setup hoặc biến môi trường
Xác định các tuyến đường trong config.yaml hoặc tạo chúng một cách linh hoạt với hermes webhook subscribe
Trỏ dịch vụ của bạn tại http://your-server:8644/webhooks/<route-name>

Thiết lập

Có hai cách để kích hoạt bộ điều hợp webhook.

Thông qua trình hướng dẫn thiết lập

hermes gateway setup

Làm theo lời nhắc để bật webhook, đặt cổng và đặt bí mật HMAC chung.

Thông qua biến môi trường

Thêm vào ~/.hermes/.env :

WEBHOOK_ENABLED=true
WEBHOOK_PORT=8644        

# default
WEBHOOK_SECRET=your-global-secret

Xác minh máy chủ

Khi cổng đang chạy:

curl http://localhost:8644/health

Phản hồi dự kiến:

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

Định cấu hình tuyến đường

Các tuyến xác định cách xử lý các nguồn webhook khác nhau. Mỗi tuyến đường là một mục nhập có tên trong platforms.webhook.extra.routes trong config.yaml của bạn.

Thuộc tính tuyến đường

Bất động sản	Bắt buộc	Mô tả
`events`	Không	Danh sách các loại sự kiện cần chấp nhận (ví dụ: `["pull_request"]` ). Nếu trống, tất cả các sự kiện đều được chấp nhận. Loại sự kiện được đọc từ `X-GitHub-Event` , `X-GitLab-Event` hoặc `event_type` trong tải trọng.
`secret`	Có	Bí mật HMAC để xác thực chữ ký. Quay trở lại `secret` toàn cầu nếu không được đặt trên tuyến đường. Đặt thành `"INSECURE_NO_AUTH"` chỉ để kiểm tra (bỏ qua xác thực).
`prompt`	Không	Chuỗi mẫu có quyền truy cập tải trọng ký hiệu dấu chấm (ví dụ: `{pull_request.title}` ). Nếu bị bỏ qua, tải trọng JSON đầy đủ sẽ được chuyển vào lời nhắc.
`skills`	Không	Danh sách tên kỹ năng cần tải để chạy đại lý.
`deliver`	Không	Nơi gửi phản hồi: `github_comment` , `telegram` , `discord` , `slack` , `signal` , `matrix` , `mattermost` , `email` , `sms` , `dingtalk` , `feishu` , `wecom` , hoặc `log` (mặc định).
`deliver_extra`	Không	Cấu hình phân phối bổ sung — các khóa phụ thuộc vào loại `deliver` (ví dụ: `repo` , `pr_number` , `chat_id` ). Các giá trị hỗ trợ các mẫu `{dot.notation}` giống như `prompt` .

Ví dụ đầy đủ

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}"
        deploy-notify:
          events: ["push"]
          secret: "deploy-secret"
          prompt: "New push to {repository.full_name} branch {ref}: {head_commit.message}"
          deliver: "telegram"

Mẫu nhắc nhở

Lời nhắc sử dụng ký hiệu dấu chấm để truy cập vào các trường lồng nhau trong tải trọng webhook:

{pull_request.title} phân giải thành payload["pull_request"]["title"]
{repository.full_name} phân giải thành payload["repository"]["full_name"]
{__raw__} — mã thông báo đặc biệt kết xuất toàn bộ tải trọng dưới dạng JSON thụt lề (cắt ngắn ở 4000 ký tự). Hữu ích để theo dõi các cảnh báo hoặc webhooks chung khi tác nhân cần bối cảnh đầy đủ.
Các khóa bị thiếu được để lại dưới dạng chuỗi {key} theo nghĩa đen (không có lỗi)
Các ký tự và danh sách lồng nhau được tuần tự hóa JSON và cắt ngắn ở 2000 ký tựBạn có thể kết hợp {__raw__} với các biến mẫu thông thường:

prompt: "PR #{pull_request.number} by {pull_request.user.login}: {__raw__}"

Nếu không có mẫu prompt nào được định cấu hình cho một tuyến đường thì toàn bộ tải trọng sẽ được kết xuất dưới dạng JSON thụt lề (bị cắt ngắn ở 4000 ký tự).

Các mẫu ký hiệu dấu chấm tương tự hoạt động ở các giá trị deliver_extra.

Cung cấp chủ đề diễn đàn

Khi gửi phản hồi webhook tới Telegram, bạn có thể nhắm mục tiêu một chủ đề diễn đàn cụ thể bằng cách đưa message_thread_id (hoặc thread_id ) vào deliver_extra :

webhooks:
  routes:
    alerts:
      events: ["alert"]
      prompt: "Alert: {__raw__}"
      deliver: "telegram"
      deliver_extra:
        chat_id: "-1001234567890"
        message_thread_id: "42"

Nếu chat_id không được cung cấp trong deliver_extra thì quá trình phân phối sẽ quay trở lại kênh chính được định cấu hình cho nền tảng đích.

Đánh giá PR GitHub (Từng bước)

Hướng dẫn này thiết lập việc xem xét mã tự động theo mọi yêu cầu kéo.

1. Tạo webhook trong GitHub

Đi tới kho lưu trữ của bạn → Cài đặt → Webhooks → Thêm webhook
Đặt URL tải trọng thành http://your-server:8644/webhooks/github-pr
Đặt Loại nội dung thành application/json
Đặt Bí mật để khớp với cấu hình tuyến đường của bạn (ví dụ: github-webhook-secret )
Trong Sự kiện nào?, chọn Để tôi chọn từng sự kiện và chọn Yêu cầu kéo
Nhấp vào Thêm webhook

2. Thêm cấu hình tuyến đường

Thêm tuyến github-pr vào ~/.hermes/config.yaml của bạn như trong ví dụ trên.

3. Đảm bảo `gh` CLI được xác thực

Loại phân phối github_comment sử dụng GitHub CLI để đăng nhận xét:

gh auth login

4. Kiểm tra nó

Mở một yêu cầu kéo trên kho lưu trữ. Webhook kích hoạt, Hermes xử lý sự kiện và đăng bình luận đánh giá về PR.

Thiết lập Webhook GitLab

Webhooks GitLab hoạt động tương tự nhưng sử dụng cơ chế xác thực khác. GitLab gửi bí mật dưới dạng tiêu đề X-Gitlab-Token đơn giản (khớp chuỗi chính xác, không phải HMAC).

1. Tạo webhook trong GitLab

Đi tới dự án của bạn → Cài đặt → Webhooks
Đặt URL thành http://your-server:8644/webhooks/gitlab-mr
Nhập Mã thông báo bí mật của bạn
Chọn Hợp nhất các sự kiện yêu cầu (và bất kỳ sự kiện nào khác mà bạn muốn)
Nhấp vào Thêm webhook

2. Thêm cấu hình tuyến đường

platforms:
  webhook:
    enabled: true
    extra:
      routes:
        gitlab-mr:
          events: ["merge_request"]
          secret: "your-gitlab-secret-token"
          prompt: |
            Review this merge request:
            Project: {project.path_with_namespace}
            MR !{object_attributes.iid}: {object_attributes.title}
            Author: {object_attributes.last_commit.author.name}
            URL: {object_attributes.url}
            Action: {object_attributes.action}
          deliver: "log"

Tùy chọn giao hàng

Trường deliver kiểm soát vị trí phản hồi của tổng đài viên sau khi xử lý sự kiện webhook.| Loại phân phối | Mô tả | |-------------|-------------| | log | Ghi lại phản hồi cho đầu ra nhật ký cổng. Đây là mặc định và rất hữu ích cho việc thử nghiệm. | | github_comment | Đăng phản hồi dưới dạng nhận xét PR/vấn đề thông qua gh CLI. Yêu cầu deliver_extra.repo và deliver_extra.pr_number . gh CLI phải được cài đặt và xác thực trên máy chủ cổng ( gh auth login ). | | telegram | Định tuyến phản hồi tới Telegram. Sử dụng kênh chính hoặc chỉ định chat_id trong deliver_extra . | | discord | Định tuyến phản hồi tới Discord. Sử dụng kênh chính hoặc chỉ định chat_id trong deliver_extra . | | slack | Định tuyến phản hồi tới Slack. Sử dụng kênh chính hoặc chỉ định chat_id trong deliver_extra . | | signal | Định tuyến phản hồi tới Signal. Sử dụng kênh chính hoặc chỉ định chat_id trong deliver_extra . | | sms | Định tuyến phản hồi tới SMS qua Twilio. Sử dụng kênh chính hoặc chỉ định chat_id trong deliver_extra . |

Để phân phối đa nền tảng (telegram, discord, Slack, signal, sms), nền tảng đích cũng phải được bật và kết nối trong cổng. Nếu không có chat_id nào được cung cấp trong deliver_extra thì phản hồi sẽ được gửi đến kênh chính đã được định cấu hình của nền tảng đó.

Đăng ký động (CLI)

Ngoài các tuyến tĩnh trong config.yaml , bạn có thể tạo đăng ký webhook một cách linh hoạt bằng cách sử dụng lệnh hermes webhook CLI. Điều này đặc biệt hữu ích khi bản thân tổng đài viên cần thiết lập trình kích hoạt theo hướng sự kiện.

Tạo đăng ký

hermes webhook subscribe github-issues \
  --events "issues" \
  --prompt "New issue #{issue.number}: {issue.title}\nBy: {issue.user.login}\n\n{issue.body}" \
  --deliver telegram \
  --deliver-chat-id "-100123456789" \
  --description "Triage new GitHub issues"

Thao tác này sẽ trả về URL webhook và bí mật HMAC được tạo tự động. Định cấu hình dịch vụ của bạn để POST tới URL đó.

Liệt kê đăng ký

hermes webhook list

Xóa đăng ký

hermes webhook remove github-issues

Kiểm tra đăng ký

hermes webhook test github-issues
hermes webhook test github-issues --payload '{"issue": {"number": 42, "title": "Test"}}'

Cách hoạt động của đăng ký động

Đăng ký được lưu trữ trong ~/.hermes/webhook_subscriptions.json
Bộ điều hợp webhook tải lại nóng tệp này theo mỗi yêu cầu đến (có giới hạn thời gian, chi phí không đáng kể)
Các tuyến tĩnh từ config.yaml luôn được ưu tiên hơn các tuyến động có cùng tên
Đăng ký động sử dụng định dạng và khả năng định tuyến giống như các tuyến tĩnh (sự kiện, mẫu lời nhắc, kỹ năng, phân phối)
Không cần khởi động lại cổng — đăng ký và nó sẽ hoạt động ngay lập tức

Đăng ký do đại lý điều khiển

Đại lý có thể tạo đăng ký thông qua công cụ đầu cuối khi được hướng dẫn bởi kỹ năng webhook-subscriptions. Yêu cầu nhân viên hỗ trợ "thiết lập webhook cho các sự cố GitHub" và nhân viên sẽ chạy lệnh hermes webhook subscribe thích hợp.

Bảo mật

Bộ điều hợp webhook bao gồm nhiều lớp bảo mật:

Xác thực chữ ký HMAC

Bộ điều hợp xác thực chữ ký webhook đến bằng phương pháp thích hợp cho từng nguồn:

GitHub: tiêu đề X-Hub-Signature-256 — bản tóm tắt hex HMAC-SHA256 có tiền tố sha256=
GitLab: tiêu đề X-Gitlab-Token — khớp chuỗi bí mật đơn giản
Chung: tiêu đề X-Webhook-Signature — bản tóm tắt hex HMAC-SHA256 thôNếu một bí mật được định cấu hình nhưng không có tiêu đề chữ ký được nhận dạng thì yêu cầu sẽ bị từ chối.

Bí mật là bắt buộc

Mỗi tuyến đường phải có một bí mật — được đặt trực tiếp trên tuyến đường đó hoặc được kế thừa từ secret toàn cầu. Các tuyến đường không có bí mật khiến bộ điều hợp không khởi động được và bị lỗi. Chỉ dành cho mục đích phát triển/thử nghiệm, bạn có thể đặt bí mật thành "INSECURE_NO_AUTH" để bỏ qua hoàn toàn quá trình xác thực.

Giới hạn tỷ lệ

Theo mặc định, mỗi tuyến được giới hạn tốc độ ở mức 30 yêu cầu mỗi phút (cửa sổ cố định). Cấu hình này trên toàn cầu:

platforms:
  webhook:
    extra:
      rate_limit: 60  

# requests per minute

Yêu cầu vượt quá giới hạn sẽ nhận được phản hồi 429 Too Many Requests.

Sự bất lực

ID gửi (từ X-GitHub-Delivery , X-Request-ID hoặc dự phòng dấu thời gian) được lưu vào bộ nhớ đệm trong 1 giờ. Các lần gửi trùng lặp (ví dụ: thử lại webhook) được âm thầm bỏ qua với phản hồi 200, ngăn chặn việc chạy tác nhân trùng lặp.

Giới hạn kích thước cơ thể

Tải trọng vượt quá 1 MB sẽ bị từ chối trước khi đọc nội dung. Cấu hình cái này:

platforms:
  webhook:
    extra:
      max_body_bytes: 2097152  

# 2 MB

Nguy cơ tiêm thuốc ngay lập tức

cảnh báo

Tải trọng webhook chứa dữ liệu do kẻ tấn công kiểm soát — Tiêu đề PR, thông báo cam kết, mô tả vấn đề, v.v. đều có thể chứa các hướng dẫn độc hại. Chạy cổng trong môi trường hộp cát (Docker, VM) khi tiếp xúc với internet. Hãy cân nhắc sử dụng phần phụ trợ của terminal Docker hoặc SSH để cách ly.

Khắc phục sự cố

Webhook không đến

Xác minh cổng được hiển thị và có thể truy cập được từ nguồn webhook
Kiểm tra quy tắc tường lửa - cổng 8644 (hoặc cổng được định cấu hình của bạn) phải mở
Xác minh đường dẫn URL khớp với: http://your-server:8644/webhooks/<route-name>
Sử dụng điểm cuối /health để xác nhận máy chủ đang chạy

Xác thực chữ ký không thành công

Đảm bảo bí mật trong cấu hình tuyến đường của bạn khớp chính xác với bí mật được định cấu hình trong nguồn webhook
Đối với GitHub, bí mật dựa trên HMAC — hãy kiểm tra X-Hub-Signature-256
Đối với GitLab, bí mật là một mã thông báo khớp đơn giản — hãy kiểm tra X-Gitlab-Token
Kiểm tra nhật ký cổng để biết cảnh báo Invalid signature

Sự kiện bị bỏ qua

Kiểm tra xem loại sự kiện có nằm trong danh sách events của tuyến đường của bạn không
Sự kiện GitHub sử dụng các giá trị như pull_request , push , issues (giá trị tiêu đề X-GitHub-Event)
Sự kiện GitLab sử dụng các giá trị như merge_request , push (giá trị tiêu đề X-GitLab-Event)
Nếu events trống hoặc không được đặt, tất cả sự kiện đều được chấp nhận

Đại lý không phản hồi

Chạy cổng ở nền trước để xem nhật ký: hermes gateway run
Kiểm tra xem mẫu lời nhắc có hiển thị chính xác không
Xác minh mục tiêu phân phối được cấu hình và kết nối

Phản hồi trùng lặp

Bộ nhớ đệm tạm thời sẽ ngăn chặn điều này — hãy kiểm tra xem nguồn webhook có đang gửi tiêu đề ID phân phối hay không ( X-GitHub-Delivery hoặc X-Request-ID )
ID phân phối được lưu trữ trong 1 giờ

`gh` Lỗi CLI (gửi nhận xét trên GitHub)

Chạy gh auth login trên máy chủ cổng
Đảm bảo người dùng GitHub được xác thực có quyền ghi vào kho lưu trữ
Kiểm tra xem gh đã được cài đặt chưa và trên PATH

Biến môi trường

Biến	Mô tả	Mặc định
`WEBHOOK_ENABLED`	Kích hoạt bộ điều hợp nền tảng webhook	`false`
`WEBHOOK_PORT`	Cổng máy chủ HTTP để nhận webhook	`8644`
`WEBHOOK_SECRET`	Bí mật HMAC toàn cầu (được sử dụng làm dự phòng khi các tuyến không chỉ định riêng)	(không có)

Bắt đầu nhanh

Thiết lập

Thông qua trình hướng dẫn thiết lập​

Thông qua biến môi trường​

Xác minh máy chủ​

Định cấu hình tuyến đường

Thuộc tính tuyến đường​

Ví dụ đầy đủ​

Mẫu nhắc nhở​

Cung cấp chủ đề diễn đàn​

Đánh giá PR GitHub (Từng bước)

1. Tạo webhook trong GitHub​

2. Thêm cấu hình tuyến đường​

3. Đảm bảo gh CLI được xác thực​

4. Kiểm tra nó​

Thiết lập Webhook GitLab

1. Tạo webhook trong GitLab​

2. Thêm cấu hình tuyến đường​

Tùy chọn giao hàng

Đăng ký động (CLI)

Tạo đăng ký​

Liệt kê đăng ký​

Xóa đăng ký​

Kiểm tra đăng ký​

Cách hoạt động của đăng ký động​

Đăng ký do đại lý điều khiển​

Bảo mật

Xác thực chữ ký HMAC​

Bí mật là bắt buộc​

Giới hạn tỷ lệ​

Sự bất lực​

Giới hạn kích thước cơ thể​

Nguy cơ tiêm thuốc ngay lập tức​

Khắc phục sự cố

Webhook không đến​

Xác thực chữ ký không thành công​

Sự kiện bị bỏ qua​

Đại lý không phản hồi​

Phản hồi trùng lặp​

gh Lỗi CLI (gửi nhận xét trên GitHub)​

Biến môi trường

Thông qua trình hướng dẫn thiết lập

Thông qua biến môi trường

Xác minh máy chủ

Thuộc tính tuyến đường

Ví dụ đầy đủ

Mẫu nhắc nhở

Cung cấp chủ đề diễn đàn

1. Tạo webhook trong GitHub

2. Thêm cấu hình tuyến đường

3. Đảm bảo `gh` CLI được xác thực

4. Kiểm tra nó

1. Tạo webhook trong GitLab

2. Thêm cấu hình tuyến đường

Tạo đăng ký

Liệt kê đăng ký

Xóa đăng ký

Kiểm tra đăng ký

Cách hoạt động của đăng ký động

Đăng ký do đại lý điều khiển

Xác thực chữ ký HMAC

Bí mật là bắt buộc

Giới hạn tỷ lệ

Sự bất lực

Giới hạn kích thước cơ thể

Nguy cơ tiêm thuốc ngay lập tức

Webhook không đến

Xác thực chữ ký không thành công

Sự kiện bị bỏ qua

Đại lý không phản hồi

Phản hồi trùng lặp

`gh` Lỗi CLI (gửi nhận xét trên GitHub)