Skip to content

Commit b42f136

Browse files
kastovkastov
authored
Routing: add webhook (#823)
1 parent ee60f0c commit b42f136

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

@@ -142,15 +146,15 @@
142146

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

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

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

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

155159
> `vlessRoute`: number | string
156160
@@ -161,7 +165,7 @@ VLESS 入站会允许配置的 UUID 第七和第八个字节被客户端修改
161165
xxxxxxxx-xxxx-0000-xxxx-xxxxxxxxxxxx
162166
```
163167

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

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

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

176180
`tls` TLS 1.0 ~ 1.3
177181

@@ -189,7 +193,7 @@ xxxxxxxx-xxxx-0000-xxxx-xxxxxxxxxxxx
189193

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

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

194198
示例：
195199

@@ -236,6 +240,60 @@ xxxxxxxx-xxxx-0000-xxxx-xxxxxxxxxxxx
236240

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

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

241299
负载均衡器配置。当一个负载均衡器生效时，它会从指定的 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

@@ -236,6 +240,60 @@ Optional. No actual effect, only used to identify the name of this rule.
236240

237241
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.
238242

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

241299
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

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

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

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

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

0 commit comments

Comments
 (0)
⚡