Skip to content

Commit 3a6af43

Browse files
kastovkastov
committed
docs: add webhook rule
1 parent 02d5344 commit 3a6af43

File tree

3 files changed

+182
-8
lines changed

3 files changed

+182
-8
lines changed

‎docs/config/routing.md‎

Lines changed: 64 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,11 @@
7272
"process": ["curl"],
7373
"outboundTag": "direct",
7474
"balancerTag": "balancer",
75-
"ruleTag": "rule name"
75+
"ruleTag": "rule name",
76+
"webhook": {
77+
"url": "https://api.example.com/alert",
78+
"deduplication": 300
79+
}
7680
}
7781
```
7882

@@ -140,15 +144,15 @@
140144

141145
> `localIP`: \[string\]
142146
143-
格式同其他 IP, 用以指定本地入站使用的 IP(使用 0.0.0.0 监听全部IP时不同的实际进入 IP 将产生不同的 localIP).
147+
格式同其他 IP, 用以指定本地入站使用的 IP(使用 0.0.0.0 监听全部 IP 时不同的实际进入 IP 将产生不同的 localIP).
144148

145149
对 UDP 无效(UDP 面向报文的原因无法跟踪), 总是看到 listen 的 IP
146150

147151
> `user`: \[string\]
148152
149153
一个数组，数组内每一项是一个邮箱地址。当某一项匹配来源用户时，此规则生效。
150154

151-
类似于域名，其也支持类似 `regexp:` 开头的正则进行匹配。（同样需要替换`\`为`\\`, 见domain部分的解释）
155+
类似于域名，其也支持类似 `regexp:` 开头的正则进行匹配。（同样需要替换`\`为`\\`, 见 domain 部分的解释）
152156

153157
> `vlessRoute`: number | string
154158
@@ -159,7 +163,7 @@ VLESS 入站会允许配置的 UUID 第七和第八个字节被客户端修改
159163
xxxxxxxx-xxxx-0000-xxxx-xxxxxxxxxxxx
160164
```
161165

162-
配置中使用的是大端序编码为uint16后的数据(听不懂的话，把这四位当成一个十六进制数并化为十进制) 如 `0001→1` `000e→14` `38b2→14514`. 这么做的原因是这里的写法同 `port`, 可以像指定 port 一样自由指定许多段进行路由。
166+
配置中使用的是大端序编码为 uint16 后的数据(听不懂的话，把这四位当成一个十六进制数并化为十进制) 如 `0001→1` `000e→14` `38b2→14514`. 这么做的原因是这里的写法同 `port`, 可以像指定 port 一样自由指定许多段进行路由。
163167

164168
> `inboundTag`: \[string\]
165169
@@ -169,7 +173,7 @@ xxxxxxxx-xxxx-0000-xxxx-xxxxxxxxxxxx
169173
170174
一个数组，数组内每一项表示一种协议。当某一个协议匹配当前连接的协议类型时，此规则生效。
171175

172-
`http` 仅支持 1.0 和 1.1 暂不支持 h2. (明文h2流量也非常少见)
176+
`http` 仅支持 1.0 和 1.1 暂不支持 h2. (明文 h2 流量也非常少见)
173177

174178
`tls` TLS 1.0 ~ 1.3
175179

@@ -187,7 +191,7 @@ xxxxxxxx-xxxx-0000-xxxx-xxxxxxxxxxxx
187191

188192
同时也支持类似 h2 的伪头部 `:method` 和 `:path` 用于匹配方法和路径(尽管在 HTTP/1.1 中是不存在这些 header 的)
189193

190-
对于 HTTP 入站的非 CONNECT 方法，可以直接获取到attrs, 对于其他入站则需要开启 sniffing 嗅探才能获得这些值用于匹配。
194+
对于 HTTP 入站的非 CONNECT 方法，可以直接获取到 attrs, 对于其他入站则需要开启 sniffing 嗅探才能获得这些值用于匹配。
191195

192196
示例：
193197

@@ -234,6 +238,60 @@ xxxxxxxx-xxxx-0000-xxxx-xxxxxxxxxxxx
234238

235239
如果设置，则命中该条规则时会在 Info 等级输出相关信息，用于调试路由具体命中了哪条规则。
236240

241+
> `webhook`: [WebhookObject](#webhookobject)
242+
243+
可选。如果设置，则命中该条规则时会向指定 URL 发送 POST 请求。
244+
245+
POST 请求中发送的数据示例：
246+
247+
```json
248+
{
249+
"email": "2", // string | null
250+
"level": null, // number | null
251+
"protocol": "tls", // string | null
252+
"network": "tcp", // string
253+
"source": "tcp:127.0.0.1:54203", // string | null
254+
"destination": "tcp:dns.google:443", // string
255+
"routeTarget": null, // string | null
256+
"originalTarget": "tcp:8.8.8.8:443", // string | null
257+
"inboundTag": "VLESS_TCP", // string | null
258+
"inboundName": "vless", // string | null
259+
"inboundLocal": "tcp:192.168.108.1:443", // string | null
260+
"outboundTag": "notify-bittorrent", // string | null
261+
"ts": 1771886901 // number
262+
}
263+
```
264+
265+
#### WebhookObject
266+
267+
```json
268+
{
269+
"url": "http://127.0.0.1:8080/api/webhook",
270+
"deduplication": 10,
271+
"headers": {
272+
"X-API-Key": "your-secret-key"
273+
}
274+
}
275+
```
276+
277+
> `url`: string
278+
279+
发送通知的目标 URL。支持标准网址和本地 Unix socket 路径。
280+
281+
- `https://api.example.com/alert` — 通过 HTTP(S) 发送通知的标准 URL。用于与外部 Web 服务或 API 集成。
282+
- `/var/run/webhook.sock` — 通过 Unix socket 发送通知，POST 请求将发送到该 socket 的根路径 `/`。
283+
- `/var/run/webhook.sock:/alert` — 通过 Unix socket 向特定端点 `/alert` 发送通知。这允许直接与本地服务集成，无需使用网络接口。
284+
- `@abstract:/webhook` — abstract socket（lock-free，仅 Linux/Android）。
285+
- `@@padded:/webhook` — 带 padding 的 abstract socket，用于 HAProxy 兼容。
286+
287+
> `deduplication`: number
288+
289+
事件去重的时间（单位：秒）。在此时间段内触发的多个相同事件，重复请求将被忽略。
290+
291+
> `headers`: object
292+
293+
HTTP 请求头。
294+
237295
### BalancerObject
238296

239297
负载均衡器配置。当一个负载均衡器生效时，它会从指定的 outbound 中，按配置选出一个最合适的 outbound，进行流量转发。

‎docs/en/config/routing.md‎

Lines changed: 59 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,11 @@ When a rule points to a load balancer, Xray will select an outbound through this
7272
"process": ["curl"],
7373
"outboundTag": "direct",
7474
"balancerTag": "balancer",
75-
"ruleTag": "rule name"
75+
"ruleTag": "rule name",
76+
"webhook": {
77+
"url": "https://api.example.com/alert",
78+
"deduplication": 300
79+
}
7680
}
7781
```
7882

@@ -234,6 +238,60 @@ Optional. No actual effect, only used to identify the name of this rule.
234238

235239
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.
236240

241+
> `webhook`: [WebhookObject](#webhookobject)
242+
243+
Optional. If set, a POST request will be sent to the specified URL when the rule is matched.
244+
245+
Example of data sent in the POST request:
246+
247+
```json
248+
{
249+
"email": "2", // string | null
250+
"level": null, // number | null
251+
"protocol": "tls", // string | null
252+
"network": "tcp", // string
253+
"source": "tcp:127.0.0.1:54203", // string | null
254+
"destination": "tcp:dns.google:443", // string
255+
"routeTarget": null, // string | null
256+
"originalTarget": "tcp:8.8.8.8:443", // string | null
257+
"inboundTag": "VLESS_TCP", // string | null
258+
"inboundName": "vless", // string | null
259+
"inboundLocal": "tcp:192.168.108.1:443", // string | null
260+
"outboundTag": "notify-bittorrent", // string | null
261+
"ts": 1771886901 // number
262+
}
263+
```
264+
265+
#### WebhookObject
266+
267+
```json
268+
{
269+
"url": "http://127.0.0.1:8080/api/webhook",
270+
"deduplication": 10,
271+
"headers": {
272+
"X-API-Key": "your-secret-key"
273+
}
274+
}
275+
```
276+
277+
> `url`: string
278+
279+
The URL to which the notification will be sent. Both standard web addresses and local Unix socket paths are supported.
280+
281+
- `https://api.example.com/alert` — a standard URL for sending notifications via HTTP(S). Used for integration with external web services or APIs.
282+
- `/var/run/webhook.sock` — sends the notification via a Unix socket, with the POST request directed to the root path `/` of the socket.
283+
- `/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.
284+
- `@abstract:/webhook` — abstract socket (lock-free, Linux/Android only).
285+
- `@@padded:/webhook` — abstract socket with padding for HAProxy compatibility.
286+
287+
> `deduplication`: number
288+
289+
The time (in seconds) for event deduplication. If multiple events are triggered within this period, duplicate requests are ignored.
290+
291+
> `headers`: object
292+
293+
HTTP request headers.
294+
237295
### BalancerObject
238296

239297
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‎

Lines changed: 59 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,11 @@
6666
"process": ["curl"],
6767
"outboundTag": "direct",
6868
"balancerTag": "balancer",
69-
"ruleTag": "rule name"
69+
"ruleTag": "rule name",
70+
"webhook": {
71+
"url": "https://api.example.com/alert",
72+
"deduplication": 300
73+
}
7074
}
7175
```
7276

@@ -226,6 +230,60 @@ JSON-объект, где ключи и значения являются стр
226230

227231
Если установлено, при совпадении с этим правилом в журнал с уровнем Info будет выводиться соответствующая информация, используемая для отладки того, какое правило маршрутизации сработало.
228232

233+
> `webhook`: [WebhookObject](#webhookobject)
234+
235+
Необязательно. Если установлено, при попадении в правило будет отправлен POST-запрос на указанный URL.
236+
237+
Пример данных, отправляемых в POST-запросе:
238+
239+
```json
240+
{
241+
"email": "2", // string | null
242+
"level": null, // number | null
243+
"protocol": "tls", // string | null
244+
"network": "tcp", // string
245+
"source": "tcp:127.0.0.1:54203", // string | null
246+
"destination": "tcp:dns.google:443", // string
247+
"routeTarget": null, // string | null
248+
"originalTarget": "tcp:8.8.8.8:443", // string | null
249+
"inboundTag": "VLESS_TCP", // string | null
250+
"inboundName": "vless", // string | null
251+
"inboundLocal": "tcp:192.168.108.1:443", // string | null
252+
"outboundTag": "notify-bittorrent", // string | null
253+
"ts": 1771886901 // number
254+
}
255+
```
256+
257+
#### WebhookObject
258+
259+
```json
260+
{
261+
"url": "http://127.0.0.1:8080/api/webhook",
262+
"deduplication": 10,
263+
"headers": {
264+
"X-API-Key": "your-secret-key"
265+
}
266+
}
267+
```
268+
269+
> `url`: string
270+
271+
URL, по которому будет отправлено уведомление. Поддерживаются как стандартные веб-адреса, так и локальные пути Unix socket.
272+
273+
- `https://api.example.com/alert` — стандартный URL для передачи уведомлений по HTTP(S). Используется при интеграции с внешними веб-сервисами или API.
274+
- `/var/run/webhook.sock` — отправка уведомления через Unix socket, POST-запрос осуществляется на корневой путь `/` данного сокета.
275+
- `/var/run/webhook.sock:/alert` — отправка уведомления через Unix socket на специфический endpoint `/alert`. Это позволяет интегрироваться с локальными сервисами напрямую, без использования сетевого интерфейса.
276+
- `@abstract:/webhook` — abstract-сокет (lock-free, только Linux/Android).
277+
- `@@padded:/webhook` — abstract-сокет с padding.
278+
279+
> `deduplication`: number
280+
281+
Время (в секундах) для дедупликации событий. При срабатывании нескольких событий в этот период дублирующие запросы игнорируются.
282+
283+
> `headers`: object
284+
285+
Заголовки HTTP-запроса.
286+
229287
### BalancerObject
230288

231289
Конфигурация балансировщика нагрузки. Когда балансировщик нагрузки активен, он выбирает наиболее подходящий исходящий канал из указанных исходящих каналов в соответствии с конфигурацией и перенаправляет трафик через него.

0 commit comments

Comments
 (0)
⚡