# Webhook Starting with version 4.8.0, AxoSyslog can collect logs via a webhook using the `webhook()` and `webhook-json()` sources. The `webhook-json()` source automatically parses the payload using the [`json-parser()`](../../docs/axosyslog-core/chapter-parsers/json-parser/index.md). Example minimal config: ``` source s_webhook { webhook-json( port(8181) paths(["/events","/events/(?P.*)"]) ); }; ``` To test the source, you can use `curl` for example, on the host where AxoSyslog is running: ``` curl -X POST --data "{'MESSAGE':'message-value'}" http://127.0.0.1:8181/events ``` This driver is actually a reusable configuration snippet based on a [custom Python source](../../docs/axosyslog-core/chapter-sources/python-source/index.md). For details on using or writing such configuration snippets, see [Reusing configuration blocks](../../docs/axosyslog-core/chapter-configuration-file/large-configs/config-blocks/index.md). You can find the source of this configuration snippet on [GitHub](). ## Query parameters If the sender includes query parameters in the URL, AxoSyslog automatically makes them available as `${webhook.query.*}`. For example, if you send data like this: ``` http://127.0.0.1:8181/events?param1=value1¶m2=value2¶m3=value3 ``` Then the values will be available as `${webhook.query.param1}`, `${webhook.query.param2}`, `${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 that setting `tls_key_file` automatically changes the default port from `80` to `443`.) To verify the certificate of the clients sending data to the webhook, set `tls_peer_verify(yes)`, and use the following options: * `tls_use_system_cert_store(no)`, or * `tls_ca_file("")`, or * `tls_ca_dir("")` ## Options ## auth_token() | ---|--- Type: | string Default: | _Description:_ You can require an authentication token from the clients as an additional layer of authentication. Do not use this under plain HTTP. When `auth_token("")` is set, AxoSyslog will only accept requests that contain the `Authorization: Basic `, `Authorization: Bearer `, or a similar header. Other requests will be rejected with 403. For example: ``` auth_token("dGVzdF9zZWdlskfoe0aF90b2tlbg==") ``` ## include_request_headers() | ---|--- Type: | `yes` or `no` Default: | `no` Available in version 4.11 and later. _Description:_ If enabled, the HTTP request headers from the webhook will available for processing as a JSON object under the `${webhook.headers}` field. This works for both versions of the source (`webhook()` and `webhook-json`). ## paths() | ---|--- Type: | JSON list Default: | `/.*` _Description:_ 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 macro values. For example, the `/events/(?P.*)` path sets 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.*)"])` ## port() | ---|--- Type: | integer Default: | See description _Description:_ The port number where the webhook is listening on, for example, `8080`. Make sure to enable the port you’ve configured on the firewall of the AxoSyslog host. The default value is `80` for HTTP webhooks, and `443` for [HTTPS webhooks](../../docs/axosyslog-core/chapter-sources/webhook/index.md#https-webhook). ## prefix() | ---|--- Type: | string Default: | _Description:_ 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 AxoSyslog. If you use such a macro name as 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, see [Hard versus soft macros](../../docs/axosyslog-core/chapter-manipulating-messages/customizing-message-format/macros-hard-vs-soft/index.md) for details). To avoid such problems, use a prefix when naming the parsed values, for example, `prefix(my-parsed-data.)` ## proxy_header() | ---|--- Type: | string Default: | Available in version 4.11 and later. _Description:_ By default, AxoSyslog assumes the client is sending data directly, without a proxy, and sets the `${SOURCEIP}` and `${SOURCEPORT}` macros to the IP and port of the peer. When `proxy_header()` is set: * `${SOURCEIP}` and `${SOURCEPORT}` will be set according to the proxy header defined in `proxy_header()`, and * the `${PEERIP}` and `${PEERPORT}` macros will contain the IP and port of the proxy. For example, to get the proxy data from the `x-forwarded-for` request header, use: ``` webhook(port(8080) proxy-header("x-forwarded-for")); ``` and include the header in the request: ``` curl -H "X-Forwarded-FOR: 1.2.3.4" -X POST --data "{}" http://127.0.0.1:8080/ ``` Note that AxoSyslog trusts only 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. ## tls_ca_dir() | ---|--- Accepted values: | Directory name Default: | none _Description:_ The name of a directory that contains a set of trusted CA certificates in PEM format. The CA certificate files have to be named after the 32-bit hash of the subject’s name. This naming can be created using the c_rehash utility in openssl. For an example, see [Configuring TLS on the AxoSyslog clients](../../docs/axosyslog-core/chapter-encrypted-transport-tls/tls-serverauth/procedure-configuring-tls-client/index.md). The AxoSyslog application uses the CA certificates in this directory to validate the certificate of the peer. This option can be used together with the optional `tls_ca_file()` option. ## tls_ca_file() | ---|--- Accepted values: | File name Default: | empty _Description:_ Optional. The name of a file that contains a set of trusted CA certificates in PEM format. The AxoSyslog application uses the CA certificates in this file to validate the certificate of the peer. Example format in configuration: ``` tls_ca_file("/etc/pki/tls/certs/ca-bundle.crt") ``` ## tls_cert_file() | ---|--- Type: | filename Default: | _Description:_ For HTTPS endpoints, set the `tls_cert_file` and `tls_key_file` options. Set `tls_cert_file` to the name of a file that contains an X.509 certificate (or a certificate chain) in PEM format, suitable as a TLS certificate, matching the private key set in the `tls_key_file()` option. The AxoSyslog application shows this certificate to the clients sending data to the webhook endpoints. If the file contains a certificate chain, the file must begin with the certificate of the host, followed by the CA certificate that signed the certificate of the host, and any other signing CAs in order. ## tls_key_file() | ---|--- Type: | filename Default: | _Description:_ The name of a file that contains an unencrypted private key in PEM format, suitable as a TLS key. If properly configured, the AxoSyslog application uses this private key with the matching certificate (set in the `tls_cert_file()` option). ## tls_peer_verify() | ---|--- Accepted values: | `yes` or `no` Default: | `no` _Description:_ Verification method of the peer. The following table summarizes the possible options and their results depending on the certificate of the peer. | The remote peer has: ---|--- no certificate | invalid certificate | valid certificate _Local peer-verify() setting_ | _no (optional-untrusted)_ | TLS-encryption | TLS-encryption | TLS-encryption _yes (required-trusted)_ | rejected connection | rejected connection | TLS-encryption For untrusted certificates only the existence of the certificate is checked, but it does not have to be valid — AxoSyslog accepts the certificate even if it is expired, signed by an unknown CA, or its CN and the name of the machine mismatches. Warning When validating a certificate, the entire certificate chain must be valid, including the CA certificate. If any certificate of the chain is invalid, AxoSyslog will reject the connection. ## tls_use_system_cert_store() | ---|--- Type: | `yes` or `no` Default: | `no` _Description:_ Use the certificate store of the system for verifying HTTPS certificates. For details, see the [curl documentation](). Last modified April 14, 2025: [Webhook source review fixes (e3bfcec7)]()