Max/XTLS_Xray-docs-next
1
0
Fork 0
mirror of https://github.com/XTLS/Xray-docs-next.git synced 2026-09-29 02:18:06 +03:00
Code Issues Packages Projects Releases Wiki Activity

Routing: add webhook (#823)

Browse Source
This commit is contained in:
Fangliding
2026-03-29 00:58:46 +08:00
parent 131e0426aa
commit 4641171321
3 changed files with 182 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/config/routing.md
+64 -6
View File
@@ -72,7 +72,11 @@
"process": ["curl"],
"outboundTag": "direct",
"balancerTag": "balancer",
"ruleTag": "rule name"
"ruleTag": "rule name",
"webhook": {
"url": "https://api.example.com/alert",
"deduplication": 300
}
}
```
@@ -142,7 +146,7 @@
> `localIP`: \[string\]
格式同其他 IP, 用以指定本地入站使用的 IP(使用 0.0.0.0 监听全部IP时不同的实际进入 IP 将产生不同的 localIP).
格式同其他 IP, 用以指定本地入站使用的 IP(使用 0.0.0.0 监听全部 IP 时不同的实际进入 IP 将产生不同的 localIP).
对 UDP 无效(UDP 面向报文的原因无法跟踪), 总是看到 listen 的 IP
@@ -150,7 +154,7 @@
一个数组，数组内每一项是一个邮箱地址。当某一项匹配来源用户时，此规则生效。
类似于域名，其也支持类似 `regexp:` 开头的正则进行匹配。（同样需要替换`\`为`\\`, 见domain部分的解释）
类似于域名，其也支持类似 `regexp:` 开头的正则进行匹配。（同样需要替换`\`为`\\`, 见 domain 部分的解释）
> `vlessRoute`: number | string
@@ -161,7 +165,7 @@ VLESS 入站会允许配置的 UUID 第七和第八个字节被客户端修改
xxxxxxxx-xxxx-0000-xxxx-xxxxxxxxxxxx
```
配置中使用的是大端序编码为uint16后的数据(听不懂的话，把这四位当成一个十六进制数并化为十进制) 如 `0001→1` `000e→14` `38b2→14514`. 这么做的原因是这里的写法同 `port`, 可以像指定 port 一样自由指定许多段进行路由。
配置中使用的是大端序编码为 uint16 后的数据(听不懂的话，把这四位当成一个十六进制数并化为十进制) 如 `0001→1` `000e→14` `38b2→14514`. 这么做的原因是这里的写法同 `port`, 可以像指定 port 一样自由指定许多段进行路由。
> `inboundTag`: \[string\]
@@ -171,7 +175,7 @@ xxxxxxxx-xxxx-0000-xxxx-xxxxxxxxxxxx
一个数组，数组内每一项表示一种协议。当某一个协议匹配当前连接的协议类型时，此规则生效。
`http` 仅支持 1.0 和 1.1 暂不支持 h2. (明文h2流量也非常少见)
`http` 仅支持 1.0 和 1.1 暂不支持 h2. (明文 h2 流量也非常少见)
`tls` TLS 1.0 ~ 1.3
@@ -189,7 +193,7 @@ xxxxxxxx-xxxx-0000-xxxx-xxxxxxxxxxxx
同时也支持类似 h2 的伪头部 `:method` 和 `:path` 用于匹配方法和路径(尽管在 HTTP/1.1 中是不存在这些 header 的)
对于 HTTP 入站的非 CONNECT 方法，可以直接获取到attrs, 对于其他入站则需要开启 sniffing 嗅探才能获得这些值用于匹配。
对于 HTTP 入站的非 CONNECT 方法，可以直接获取到 attrs, 对于其他入站则需要开启 sniffing 嗅探才能获得这些值用于匹配。
示例：
@@ -236,6 +240,60 @@ xxxxxxxx-xxxx-0000-xxxx-xxxxxxxxxxxx
如果设置，则命中该条规则时会在 Info 等级输出相关信息，用于调试路由具体命中了哪条规则。
> `webhook`: [WebhookObject](#webhookobject)
可选。如果设置，则命中该条规则时会向指定 URL 发送 POST 请求。
POST 请求中发送的数据示例：
```json
{
"email": "2", // string | null
"level": null, // number | null
"protocol": "tls", // string | null
"network": "tcp", // string
"source": "tcp:127.0.0.1:54203", // string | null
"destination": "tcp:dns.google:443", // string
"routeTarget": null, // string | null
"originalTarget": "tcp:8.8.8.8:443", // string | null
"inboundTag": "VLESS_TCP", // string | null
"inboundName": "vless", // string | null
"inboundLocal": "tcp:192.168.108.1:443", // string | null
"outboundTag": "notify-bittorrent", // string | null
"ts": 1771886901 // number
}
```
#### WebhookObject
```json
{
"url": "http://127.0.0.1:8080/api/webhook",
"deduplication": 10,
"headers": {
"X-API-Key": "your-secret-key"
}
}
```
> `url`: string
发送通知的目标 URL。支持标准网址和本地 Unix socket 路径。
- `https://api.example.com/alert` — 通过 HTTP(S) 发送通知的标准 URL。用于与外部 Web 服务或 API 集成。
- `/var/run/webhook.sock` — 通过 Unix socket 发送通知，POST 请求将发送到该 socket 的根路径 `/`。
- `/var/run/webhook.sock:/alert` — 通过 Unix socket 向特定端点 `/alert` 发送通知。这允许直接与本地服务集成，无需使用网络接口。
- `@abstract:/webhook` — abstract socket（lock-free，仅 Linux/Android）。
- `@@padded:/webhook` — 带 padding 的 abstract socket，用于 HAProxy 兼容。
> `deduplication`: number
事件去重的时间（单位：秒）。在此时间段内触发的多个相同事件，重复请求将被忽略。
> `headers`: object
HTTP 请求头。
### BalancerObject
负载均衡器配置。当一个负载均衡器生效时，它会从指定的 outbound 中，按配置选出一个最合适的 outbound，进行流量转发。
docs/en/config/routing.md
+59 -1
View File
@@ -72,7 +72,11 @@ When a rule points to a load balancer, Xray will select an outbound through this
"process": ["curl"],
"outboundTag": "direct",
"balancerTag": "balancer",
"ruleTag": "rule name"
"ruleTag": "rule name",
"webhook": {
"url": "https://api.example.com/alert",
"deduplication": 300
}
}
```
@@ -236,6 +240,60 @@ Optional. No actual effect, only used to identify the name of this rule.
If set, information regarding this rule will be output at the Info level when the rule is matched, used for debugging which specific rule was hit.
> `webhook`: [WebhookObject](#webhookobject)
Optional. If set, a POST request will be sent to the specified URL when the rule is matched.
Example of data sent in the POST request:
```json
{
"email": "2", // string | null
"level": null, // number | null
"protocol": "tls", // string | null
"network": "tcp", // string
"source": "tcp:127.0.0.1:54203", // string | null
"destination": "tcp:dns.google:443", // string
"routeTarget": null, // string | null
"originalTarget": "tcp:8.8.8.8:443", // string | null
"inboundTag": "VLESS_TCP", // string | null
"inboundName": "vless", // string | null
"inboundLocal": "tcp:192.168.108.1:443", // string | null
"outboundTag": "notify-bittorrent", // string | null
"ts": 1771886901 // number
}
```
#### WebhookObject
```json
{
"url": "http://127.0.0.1:8080/api/webhook",
"deduplication": 10,
"headers": {
"X-API-Key": "your-secret-key"
}
}
```
> `url`: string
The URL to which the notification will be sent. Both standard web addresses and local Unix socket paths are supported.
- `https://api.example.com/alert` — a standard URL for sending notifications via HTTP(S). Used for integration with external web services or APIs.
- `/var/run/webhook.sock` — sends the notification via a Unix socket, with the POST request directed to the root path `/` of the socket.
- `/var/run/webhook.sock:/alert` — sends the notification via a Unix socket to a specific endpoint `/alert`. This allows direct integration with local services without using a network interface.
- `@abstract:/webhook` — abstract socket (lock-free, Linux/Android only).
- `@@padded:/webhook` — abstract socket with padding for HAProxy compatibility.
> `deduplication`: number
The time (in seconds) for event deduplication. If multiple events are triggered within this period, duplicate requests are ignored.
> `headers`: object
HTTP request headers.
### BalancerObject
Load balancer configuration. When a load balancer takes effect, it selects the most suitable outbound from the specified outbounds according to the configuration and forwards the traffic.
docs/ru/config/routing.md
+59 -1
View File
@@ -66,7 +66,11 @@
"process": ["curl"],
"outboundTag": "direct",
"balancerTag": "balancer",
"ruleTag": "rule name"
"ruleTag": "rule name",
"webhook": {
"url": "https://api.example.com/alert",
"deduplication": 300
}
}
```
@@ -228,6 +232,60 @@ JSON-объект, где ключи и значения являются стр
Если установлено, при совпадении с этим правилом в журнал с уровнем Info будет выводиться соответствующая информация, используемая для отладки того, какое правило маршрутизации сработало.
> `webhook`: [WebhookObject](#webhookobject)
Необязательно. Если установлено, при попадении в правило будет отправлен POST-запрос на указанный URL.
Пример данных, отправляемых в POST-запросе:
```json
{
"email": "2", // string | null
"level": null, // number | null
"protocol": "tls", // string | null
"network": "tcp", // string
"source": "tcp:127.0.0.1:54203", // string | null
"destination": "tcp:dns.google:443", // string
"routeTarget": null, // string | null
"originalTarget": "tcp:8.8.8.8:443", // string | null
"inboundTag": "VLESS_TCP", // string | null
"inboundName": "vless", // string | null
"inboundLocal": "tcp:192.168.108.1:443", // string | null
"outboundTag": "notify-bittorrent", // string | null
"ts": 1771886901 // number
}
```
#### WebhookObject
```json
{
"url": "http://127.0.0.1:8080/api/webhook",
"deduplication": 10,
"headers": {
"X-API-Key": "your-secret-key"
}
}
```
> `url`: string
URL, по которому будет отправлено уведомление. Поддерживаются как стандартные веб-адреса, так и локальные пути Unix socket.
- `https://api.example.com/alert` — стандартный URL для передачи уведомлений по HTTP(S). Используется при интеграции с внешними веб-сервисами или API.
- `/var/run/webhook.sock` — отправка уведомления через Unix socket, POST-запрос осуществляется на корневой путь `/` данного сокета.
- `/var/run/webhook.sock:/alert` — отправка уведомления через Unix socket на специфический endpoint `/alert`. Это позволяет интегрироваться с локальными сервисами напрямую, без использования сетевого интерфейса.
- `@abstract:/webhook` — abstract-сокет (lock-free, только Linux/Android).
- `@@padded:/webhook` — abstract-сокет с padding.
> `deduplication`: number
Время (в секундах) для дедупликации событий. При срабатывании нескольких событий в этот период дублирующие запросы игнорируются.
> `headers`: object
Заголовки HTTP-запроса.
### BalancerObject
Конфигурация балансировщика нагрузки. Когда балансировщик нагрузки активен, он выбирает наиболее подходящий исходящий канал из указанных исходящих каналов в соответствии с конфигурацией и перенаправляет трафик через него.