webhook source

_data/external_links.yml

@@ -733,6 +733,11 @@ gh-sumo:
   id: gh-sumo
   url: https://github.com/syslog-ng/syslog-ng/blob/master/scl/sumologic/sumologic.conf
   title: [ "Sumo Logic configuration snippet on GitHub" ]
+
+gh-webhook:
+  id: gh-webhook
+  url: https://github.com/syslog-ng/syslog-ng/blob/develop/modules/python-modules/syslogng/modules/webhook/scl/webhook.conf
+  title: [ "Webhook config file on GitHub" ]
 
 gh-websense:
   id: gh-websense

doc/_admin-guide/060_Sources/240_webhook/000_webhook_options.md

@@ -0,0 +1,97 @@
+---
+title: webhook() source options
+src: 'webhook'
+id: adm-src-webhook-opt
+description: >-
+    This section describes the options of the webhook source in {{ site.product.short_name }}.
+---
+
+The `webhook()` and `webhook-json()` drivers have the following options:
+
+## auth_token()
+
+|Type:|   string|
+|Default:|  none|
+
+*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`.
+
+### Example:
+
+```config
+auth_token("dGVzdF9zZWdlskfoe0aF90b2tlbg==")
+```
+
+## include_request_headers()
+
+|Type:|   `yes`, `no`|
+|Default:|       `no`|
+
+*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.
+
+## paths()
+
+|Type:|   JSON list|
+|Default:|    `/.*`|
+
+*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.
+
+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`.
+
+You can set multiple endpoints, for example, paths(["/events","/events/(?P\<HOST\>.*)"])
+
+## port()
+
+|Type:|   integer|
+|Default:|    `80`(webhook), `443`(HTTPS webhook)|
+
+*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.
+
+## prefix()
+
+|Type:|   string|
+|Default:|      |
+
+*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.
+
+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.)`.
+
+## proxy_header()
+
+|Type:|   string|
+|Default:|      |
+
+*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.
+
+When `proxy_header()` is set the following conditions apply:
+* `${SOURCEIP}` and `${SOURCEPORT}` macros will be set according to the proxy header defined in proxy_header().
+* The `${PEERIP}` and `${PEERPORT}` macros will contain the IP and port of the proxy.
+
+### Example: getting proxy data from `x-forwarded-for` request header
+
+```config
+webhook(port(8080) proxy-header("x-forwarded-for"));
+```
+
+Header in the request:
+
+```config
+curl  -H "X-Forwarded-FOR: 1.2.3.4" -X POST --data "{}" http://127.0.0.1:8080/
+```
+
+**NOTE:** 
+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.
+{: .notice--info}
+
+{% include doc/admin-guide/options/ca-dir.md %}
+
+{% include doc/admin-guide/options/ca-file.md %}
+
+{% include doc/admin-guide/options/cert-file.md %}
+
+{% include doc/admin-guide/options/key-file.md %}
+
+{% include doc/admin-guide/options/peer-verify.md %}
+
+{% include doc/admin-guide/options/use-system-cert-store.md %}
+
+> *Copyright © 2025 Axoflow*

doc/_admin-guide/060_Sources/240_webhook/README.md

@@ -0,0 +1,50 @@
+---
+title: 'Webhook source'
+short_title: webhook
+id: adm-src-webhook
+description: >-
+        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()`.
+---
+
+**Declaration**
+
+```config
+source s_webhook {
+webhook-json(
+    port(8181)
+    paths(["/events","/events/(?P<HOST>.*)"])
+    );
+};
+```
+
+On hosts where {{ site.product.short_name }} is running, you can use the curl command to test the source.
+
+```config
+curl -X POST --data "{'MESSAGE':'message-value'}" http://127.0.0.1:8181/events
+```
+
+## Query parameters
+
+You can include query parameters in the URL and {{ site.product.short_name }} automatically makes them available as `${webhook.query.*}`.
+
+### Example: Sending data with query parameters
+
+```config
+http://127.0.0.1:8181/events?param1=value1&param2=value2&param3=value3
+```
+
+This way, the available values become `${webhook.query.param1}`, `${webhook.query.param2}` and `${webhook.query.param3}`.
+
+## HTTPS Webhook
+
+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.
+
+**NOTE:** Setting `tls_key_file` automatically changes the default port from `80` to `443`.
+{: .notice--info}
+
+To verify the certificate of the clients sending data to the webhook, set `tls_peer_verify(yes)`, and use one of the following options:
+* `tls_use_system_cert_store(no)`
+* `tls_ca_file("")`
+* `tls_ca_dir("")`
+
+> *Copyright © 2025 Axoflow*