Chuyển tới nội dung chính

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ả.

Video hướng dẫn`<div style=&#123;&#123;position: 'relative', width: '100%', aspectRatio: '16 / 9', marginBottom: '1.5rem'}}>​

<iframe src="https://www.youtube.com/embed/WNYe5mD4fY8" title="Hermes Agent — Webhooks Tutorial" style=&#123;&#123;position: 'absolute', top: 0, left: 0, width: '100%', height: '100%', border: 0}} allow="accelerometer; autoplay; CLIpboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowFullScreen / </div

Bắt đầu nhanh​

  1. Kích hoạt thông qua Hermes gateway setup hoặc biến môi trường

  2. 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

  3. Trỏ dịch vụ của bạn tại `http://your-server:8644/webhooks/&lt;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

:

`bash
WEBHOOK_ENABLED=true
WEBHOOK_PORT=8644        # default
WEBHOOK_SECRET=your-global-secret

`

### Xác minh máy chủ

Khi cổng đang chạy:

`bash
curl http://localhost:8644/health

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

`JSON
\&#123;"status": "ok", "platform": "webhook"&#125;

`

---

## Định cấu hình các tuyến đường &#123;#configuring-routes&#125;

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. Đặ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ụ: 

\&#123;pull_request.title&#125;

). 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

, 
`sms

, 
`WhatsApp

, 
`Matrix

, 
`Mattermost

, 
`homeassistant

, 
`email

, 
`DingTalk

, 
`Feishu

, 
`WeCom

, 
`weixin

, 
`BlueBubbles

, 
`qqbot
` hoặc 
`log
` (mặc định). |
| 
`deliver_extra
` | Không | Cấu hình phân phối bổ sung — các khóa tùy thuộc vào loại 
`deliver
` (ví dụ: 
`repo

, 
`pr_number

, 
`chat_id

). Các giá trị hỗ trợ các mẫu 

\&#123;dot.notation&#125;
` giống như 
`prompt

. |
| 
`deliver_only
` | Không | Nếu 
`true

, hãy bỏ qua hoàn toàn tác nhân - mẫu 
`prompt
` được hiển thị sẽ trở thành thông báo theo nghĩa đen được gửi. Chi phí LLM bằng không, giao hàng dưới giây. Xem [Direct Delivery Mode](#direct-delivery-mode) để biết các trường hợp sử dụng. Yêu cầu 
`deliver
` phải là mục tiêu thực sự (không phải 
`log

). |

### Ví dụ đầy đủ

`YAML
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: \&#123;repository.full_name&#125;
            PR #\&#123;number&#125;: \&#123;pull_request.title&#125;
            Author: \&#123;pull_request.user.login&#125;
            URL: \&#123;pull_request.html_url&#125;
            Diff URL: \&#123;pull_request.diff_url&#125;
            Action: \&#123;action&#125;
          skills: ["GitHub-code-review"]
          deliver: "GitHub_comment"
          deliver_extra:
            repo: "\&#123;repository.full_name&#125;"
            pr_number: "\&#123;number&#125;"
        deploy-notify:
          events: ["push"]
          secret: "deploy-secret"
          prompt: "New push to \&#123;repository.full_name&#125; branch \&#123;ref&#125;: \&#123;head_commit.message&#125;"
          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:
- 

\&#123;pull_request.title&#125;
` phân giải thành 
`payload["pull_request"]["title"]

`
- 

\&#123;repository.full_name&#125;
` phân giải thành 
`payload["repository"]["full_name"]

- 

\&#123;__raw__&#125;
` — 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 

\&#123;key&#125;
` 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 

\&#123;__raw__&#125;
` với các biến mẫu thông thường:

``` yaml
prompt: "PR #\&#123;pull_request.number&#125; by \&#123;pull_request.user.login&#125;: \&#123;__raw__&#125;"

`
``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ề (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

:

`YAML
webhooks:
  routes:
    alerts:
      events: ["alert"]
      prompt: "Alert: \&#123;__raw__&#125;"
      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ì việc 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) &#123;#GitHub-pr-review&#125;

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
1. Đi tới kho lưu trữ của bạn → **Cài đặt** → **Webhooks** → **Thêm webhook**

2. Đặt **URL tải trọng** thành 
`http://your-server:8644/webhooks/GitHub-pr

3. Đặt **Loại nội dung** thành 
`application/JSON

4. Đặt **Bí mật** để khớp với cấu hình tuyến đường của bạn (ví dụ: 
`GitHub-webhook-secret

)
5. 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**
6. 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:

``` bash
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 &#123;#GitLab-webhook-setup&#125;

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
1. Đi tới dự án của bạn → **Cài đặt** → **Webhooks**

2. Đặt **URL** thành 
`http://your-server:8644/webhooks/GitLab-mr

3. Nhập **Mã thông báo bí mật** của bạn
4. 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)
5. Nhấp vào **Thêm webhook**

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

``` yaml
platforms:
  webhook:
    enabled: true
    extra:
      routes:
        GitLab-mr:
          events: ["merge_request"]
          secret: "your-GitLab-secret-token"
          prompt: |
            Review this merge request:
            Project: \&#123;project.path_with_namespace&#125;
            MR !\&#123;object_attributes.iid&#125;: \&#123;object_attributes.title&#125;
            Author: \&#123;object_attributes.last_commit.author.name&#125;
            URL: \&#123;object_attributes.url&#125;
            Action: \&#123;object_attributes.action&#125;
          deliver: "log"

`

---

## Tùy chọn giao hàng &#123;#delivery-options&#125;

Trường 
`deliver
` kiểm soát nơi 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

. |
| 
`WhatsApp
` | Định tuyến phản hồi tới WhatsApp. Sử dụng kênh chính hoặc chỉ định 
`chat_id
` trong 
`deliver_extra

. |
| 
`Matrix
` | Định tuyến phản hồi tới Matrix. Sử dụng kênh chính hoặc chỉ định 
`chat_id
` trong 
`deliver_extra

. |
| 
`Mattermost
` | Định tuyến phản hồi đến Matter Extreme. Sử dụng kênh chính hoặc chỉ định 
`chat_id
` trong 
`deliver_extra

. |
| 
`homeassistant
` | Định tuyến phản hồi tới Trợ lý gia đình. Sử dụng kênh chính hoặc chỉ định 
`chat_id
` trong 
`deliver_extra

. |
| 
`email
` | Định tuyến phản hồi tới Email. Sử dụng kênh chính hoặc chỉ định 
`chat_id
` trong 
`deliver_extra

. |
| 
`DingTalk
` | Định tuyến phản hồi tới DingTalk. Sử dụng kênh chính hoặc chỉ định 
`chat_id
` trong 
`deliver_extra

. |
| 
`Feishu
` | Định tuyến phản hồi tới Feishu/Lark. Sử dụng kênh chính hoặc chỉ định 
`chat_id
` trong 
`deliver_extra

. |
| 
`WeCom
` | Định tuyến phản hồi tới WeCom. Sử dụng kênh chính hoặc chỉ định 
`chat_id
` trong 
`deliver_extra

. |
| 
`weixin
` | Định tuyến phản hồi tới Weixin (WeChat). Sử dụng kênh chính hoặc chỉ định 
`chat_id
` trong 
`deliver_extra

. |
| 
`BlueBubbles
` | Định tuyến phản hồi tới BlueBubbles (iMessage). 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, nền tảng đích cũng phải được bật và kết nối trong cổng. Nếu 
`chat_id
` không đượ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 đó.

---

## Chế độ giao hàng trực tiếp &#123;#direct-delivery-mode&#125;

Theo mặc định, mỗi webhook POST sẽ kích hoạt một lần chạy tác nhân — tải trọng trở thành lời nhắc, tác nhân xử lý nó và phản hồi của tác nhân được gửi. Điều này sẽ tiêu tốn mã thông báo LLM trong mỗi sự kiện.

Đối với các trường hợp sử dụng mà bạn chỉ muốn **đẩy một thông báo đơn giản** — không cần lý do, không có vòng lặp tác nhân, chỉ cần gửi tin nhắn — hãy đặt 
`deliver_only: true
` trên tuyến đường. Mẫu 
`prompt
` được kết xuất sẽ trở thành nội dung thông báo theo nghĩa đen và bộ điều hợp sẽ gửi mẫu đó trực tiếp đến mục tiêu phân phối đã định cấu hình.

### Khi nào nên sử dụng giao hàng trực tiếp
- **Đẩy dịch vụ bên ngoài** — Webhook Supabase/Firebase kích hoạt khi có thay đổi về cơ sở dữ liệu → thông báo ngay cho người dùng trong Telegram

- **Cảnh báo giám sát** — Webhook cảnh báo Datadog/Grafana → đẩy tới kênh Discord
- **ping giữa các tác nhân** — Tác nhân A thông báo cho người dùng của Tác nhân B rằng một tác vụ dài hạn đã hoàn thành
- **Hoàn thành công việc nền** — Hoàn thành công việc định kỳ → đăng kết quả lên Slack

Lợi ích:
- **Không có mã thông báo LLM** — đại lý không bao giờ được gọi
- **Phân phối dưới giây** — một cuộc gọi bộ chuyển đổi duy nhất, không có vòng lặp lý luận
- **Bảo mật tương tự như chế độ tác nhân** — Xác thực HMAC, giới hạn tốc độ, giá trị tạm thời và giới hạn kích thước nội dung vẫn được áp dụng
- **Phản hồi đồng bộ** — POST trả về 
`200 OK
` sau khi gửi thành công hoặc 
`502
` nếu mục tiêu từ chối nó, để dịch vụ ngược tuyến của bạn có thể thử lại một cách thông minh

### Ví dụ: Đẩy Telegram từ Supabase

``` yaml
platforms:
  webhook:
    enabled: true
    extra:
      port: 8644
      secret: "global-secret"
      routes:
        antenna-matches:
          secret: "antenna-webhook-secret"
          deliver: "Telegram"
          deliver_only: true
          prompt: "🎉 New match: \&#123;match.user_name&#125; matched with you!"
          deliver_extra:
            chat_id: "\&#123;match.Telegram_chat_id&#125;"

`
``Hàm Supabase Edge của bạn ký tải trọng bằng HMAC-SHA256 và POST tới 
`https://your-server:8644/webhooks/antenna-matches

. Bộ điều hợp webhook xác thực chữ ký, hiển thị mẫu từ tải trọng, gửi tới Telegram và trả về 
`200 OK

.

### Ví dụ: Đăng ký động qua CLI

`bash
Hermes webhook subscribe antenna-matches \

  --deliver Telegram \
  --deliver-chat-id "123456789" \
  --deliver-only \
  --prompt "🎉 New match: \&#123;match.user_name&#125; matched with you!" \
  --description "Antenna match notifications"

`

### Mã phản hồi

| Trạng thái | Ý nghĩa |
|--------|----------|
| 
`200 OK
` | Đã giao hàng thành công. Thân máy: 

\&#123;"status": "delivered", "route": "...", "target": "...", "delivery_id": "..."&#125;
` |
| 
`200 OK
` (trạng thái=trùng lặp) | Sao chép ID 
`X-GitHub-Delivery
` trong TTL tạm thời (1 giờ). Không được giao lại. |
| 
`401 UnauthoriZed
` | Chữ ký HMAC không hợp lệ hoặc bị thiếu. |
| 
`400 Bad Request
` | Nội dung JSON không đúng định dạng. |
| 
`404 Not Found
` | Tên tuyến đường không xác định. |
| 
`413 Payload Too Large
` | Thân máy vượt quá 
`max_body_bytes

. |
| 
`429 Too Many Requests
` | Đã vượt quá giới hạn tốc độ tuyến đường. |
| 
`502 Bad Gateway
` | Bộ điều hợp mục tiêu đã từ chối thông báo hoặc nêu ra. Lỗi được ghi lại phía máy chủ; nội dung phản hồi là 
`Delivery failed
` chung để tránh rò rỉ phần bên trong bộ điều hợp. |

### Các vấn đề về cấu hình
- 
`deliver_only: true
` yêu cầu 
`deliver
` phải là mục tiêu thực sự. 
`deliver: log
` (hoặc bỏ qua 
`deliver

) bị từ chối khi khởi động — bộ điều hợp từ chối khởi động nếu tìm thấy tuyến được định cấu hình sai.
- Trường 
`skills
` bị bỏ qua trong chế độ phân phối trực tiếp (không có tác nhân nào chạy nên không có gì để đưa kỹ năng vào).
- Kết xuất mẫu sử dụng cú pháp 

\&#123;dot.notation&#125;
` giống như chế độ tác nhân, bao gồm mã thông báo 

\&#123;__raw__&#125;

.
- Idempotency sử dụng cùng một tiêu đề 
`X-GitHub-Delivery
` / 
`X-Request-ID
` — thử lại với cùng một ID trả về 
`status=duplicate
` và KHÔNG phân phối lại.

---

## Đăng ký động (CLI) &#123;# đăng ký động&#125;

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ý

``` bash
Hermes webhook subscribe GitHub-issues \

  --events "issues" \
  --prompt "New issue #\&#123;issue.number&#125;: \&#123;issue.title&#125;\nBy: \&#123;issue.user.login&#125;\n\n\&#123;issue.body&#125;" \
  --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ý

``` bash
Hermes webhook list

`

### Xóa đăng ký

`bash
Hermes webhook remove GitHub-issues

`

### Kiểm tra đăng ký

`bash
Hermes webhook test GitHub-issues
Hermes webhook test GitHub-issues --payload '\&#123;"issue": \&#123;"number": 42, "title": "Test"&#125;&#125;'

`

### 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 &#123;#bảo mật&#125;

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.

INSECURE_NO_AUTH
` chỉ được chấp nhận khi cổng được liên kết với máy chủ loopback (
`127.0.0.1

, 
`localhost

, 

::1

). Nếu nó được kết hợp với một liên kết không lặp lại, chẳng hạn như 
`0.0.0.0
` hoặc IP LAN, thì bộ điều hợp sẽ từ chối khởi động — điều này ngăn việc vô tình làm lộ điểm cuối không được xác thực trên giao diện công cộng.

### 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:

``` yaml
platforms:
  webhook:
    extra:
      rate_limit: 60  # requests per minute

`
``Các 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 phân phố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 bằng 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:

`YAML
platforms:
  webhook:
    extra:
      max_body_bytes: 2097152  # 2 MB

`

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

:::warning
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ố &#123;#troubleshooting&#125;

### 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ở
- Kiểm tra đường dẫn URL trùng khớp: 
`http://your-server:8644/webhooks/&lt;route-name

- Sử dụng endpoint 

/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ó trong danh sách 
`events
` trên 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 chưa được đặt, tất cả các sự kiện đều được chấp nhận

### Đại lý không phản hồi
- Chạy cổng ở foreground để xem log: 
`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ộ đệ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ờ

### Lỗi 
`gh
` CLI (gửi bình luậ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 và trên PATH chưa

---

## Biến môi trường &#123;#environment-variables&#125;

| 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ó)_ |