Skip to content

Commit 1f8dbf0

Browse files
webhook source (#198)
Included webhook() source
2 parents 48811f0 + 4339126 commit 1f8dbf0

File tree

3 files changed

+152
-0
lines changed

3 files changed

+152
-0
lines changed

_data/external_links.yml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -733,6 +733,11 @@ gh-sumo:
733733
id: gh-sumo
734734
url: https://github.com/syslog-ng/syslog-ng/blob/master/scl/sumologic/sumologic.conf
735735
title: [ "Sumo Logic configuration snippet on GitHub" ]
736+
737+
gh-webhook:
738+
id: gh-webhook
739+
url: https://github.com/syslog-ng/syslog-ng/blob/develop/modules/python-modules/syslogng/modules/webhook/scl/webhook.conf
740+
title: [ "Webhook config file on GitHub" ]
736741

737742
gh-websense:
738743
id: gh-websense
Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
title: webhook() source options
3+
src: 'webhook'
4+
id: adm-src-webhook-opt
5+
description: >-
6+
This section describes the options of the webhook source in {{ site.product.short_name }}.
7+
---
8+
9+
The `webhook()` and `webhook-json()` drivers have the following options:
10+
11+
## auth_token()
12+
13+
|Type:| string|
14+
|Default:| none|
15+
16+
*Description:* You can request an authentication token from the clients as an additional method of validation. Do not use this under plain HTTP. When `auth_token("<token>")` is set, {{ site.product.short_name }} only accepts requests that contain the Authorization: Basic \<token\>, Authorization: Bearer \<token\>, or a similar header. Other requests will be rejected with `403`.
17+
18+
### Example:
19+
20+
```config
21+
auth_token("dGVzdF9zZWdlskfoe0aF90b2tlbg==")
22+
```
23+
24+
## include_request_headers()
25+
26+
|Type:| `yes`, `no`|
27+
|Default:| `no`|
28+
29+
*Description:* If enabled, the HTTP request headers from the webhook are available for processing as a JSON object under the `${webhook.headers}` field. This option works for `webhook()` and for `webhook-json()` as well.
30+
31+
## paths()
32+
33+
|Type:| JSON list|
34+
|Default:| `/.*`|
35+
36+
*Description:* The `paths()` option sets the endpoints where the webhook will receive data. You can use static paths, or regular expressions. In regular expressions you can use named capture groups to automatically set the macro values.
37+
38+
For example, the `/events/(?P<HOST>.*)` path specifies the hostname for the data received in the request based on the second part of the URL: a request to the `/events/my-example-host` URL sets the host field of that message to `my-example-host`.
39+
40+
You can set multiple endpoints, for example, paths(["/events","/events/(?P\<HOST\>.*)"])
41+
42+
## port()
43+
44+
|Type:| integer|
45+
|Default:| `80`(webhook), `443`(HTTPS webhook)|
46+
47+
*Description:* Specifies the port-number where the webhook is listening on, for example, `8080`. Make sure to enable the port you have configured on the firewall of the {{ site.product.short_name }} host. The default value is `80` for HTTP webhooks, and `443` for HTTPS webhooks.
48+
49+
## prefix()
50+
51+
|Type:| string|
52+
|Default:| |
53+
54+
*Description:* This option can be used to insert a prefix before the name part of the parsed name-value pairs to help further processing when using the `webhook-json()` source. For example, to insert the `webhook.` prefix, use the `prefix(webhook.)` option.
55+
56+
Names starting with a dot (for example, .example) are reserved for use by {{ site.product.short_name }}. If you attempt use a macro name identical to the name of a parsed value, it will attempt to replace the original value of the macro (note that only soft macros can be overwritten, for more information, see Hard versus soft macros). To avoid such problems, use a prefix when naming the parsed values, for example, `prefix(my-parsed-data.)`.
57+
58+
## proxy_header()
59+
60+
|Type:| string|
61+
|Default:| |
62+
63+
*Description:* By default, {{ site.product.short_name }} expects data to be sent directly, without a proxy, and sets the `${SOURCEIP}` and `${SOURCEPORT}` macros to the IP and port of the peer.
64+
65+
When `proxy_header()` is set the following conditions apply:
66+
* `${SOURCEIP}` and `${SOURCEPORT}` macros will be set according to the proxy header defined in proxy_header().
67+
* The `${PEERIP}` and `${PEERPORT}` macros will contain the IP and port of the proxy.
68+
69+
### Example: getting proxy data from `x-forwarded-for` request header
70+
71+
```config
72+
webhook(port(8080) proxy-header("x-forwarded-for"));
73+
```
74+
75+
Header in the request:
76+
77+
```config
78+
curl -H "X-Forwarded-FOR: 1.2.3.4" -X POST --data "{}" http://127.0.0.1:8080/
79+
```
80+
81+
**NOTE:**
82+
Note that {{ site.product.short_name }} only trusts the header that is specified in the `proxy_header()` option. If the request includes multiple headers with the specified name, the last one is used.
83+
{: .notice--info}
84+
85+
{% include doc/admin-guide/options/ca-dir.md %}
86+
87+
{% include doc/admin-guide/options/ca-file.md %}
88+
89+
{% include doc/admin-guide/options/cert-file.md %}
90+
91+
{% include doc/admin-guide/options/key-file.md %}
92+
93+
{% include doc/admin-guide/options/peer-verify.md %}
94+
95+
{% include doc/admin-guide/options/use-system-cert-store.md %}
96+
97+
> *Copyright © 2025 Axoflow*
Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
title: 'Webhook source'
3+
short_title: webhook
4+
id: adm-src-webhook
5+
description: >-
6+
From version 4.8.0 and onwards, {{ site.product.short_name }} can collect logs through a webhook using the `webhook()` and `webhook-json()` sources. The webhook-json() source automatically parses the payload using the `json-parser()`.
7+
---
8+
9+
**Declaration**
10+
11+
```config
12+
source s_webhook {
13+
webhook-json(
14+
port(8181)
15+
paths(["/events","/events/(?P<HOST>.*)"])
16+
);
17+
};
18+
```
19+
20+
On hosts where {{ site.product.short_name }} is running, you can use the curl command to test the source.
21+
22+
```config
23+
curl -X POST --data "{'MESSAGE':'message-value'}" http://127.0.0.1:8181/events
24+
```
25+
26+
## Query parameters
27+
28+
You can include query parameters in the URL and {{ site.product.short_name }} automatically makes them available as `${webhook.query.*}`.
29+
30+
### Example: Sending data with query parameters
31+
32+
```config
33+
http://127.0.0.1:8181/events?param1=value1&param2=value2&param3=value3
34+
```
35+
36+
This way, the available values become `${webhook.query.param1}`, `${webhook.query.param2}` and `${webhook.query.param3}`.
37+
38+
## HTTPS Webhook
39+
40+
To receive data using HTTPS, configure a certificate and a private key for the webhook using the `tls_cert_file` and `tls_key_file` options.
41+
42+
**NOTE:** Setting `tls_key_file` automatically changes the default port from `80` to `443`.
43+
{: .notice--info}
44+
45+
To verify the certificate of the clients sending data to the webhook, set `tls_peer_verify(yes)`, and use one of the following options:
46+
* `tls_use_system_cert_store(no)`
47+
* `tls_ca_file("")`
48+
* `tls_ca_dir("")`
49+
50+
> *Copyright © 2025 Axoflow*

0 commit comments

Comments
 (0)