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().

Example minimal config:

source s_webhook {
webhook-json(
    port(8181)
    paths(["/events","/events/(?P<HOST>.*)"])
    );
};

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. For details on using or writing such configuration snippets, see Reusing configuration blocks. 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&param2=value2&param3=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()

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("<token>") is set, AxoSyslog will only accept requests that contain the Authorization: Basic <token>, Authorization: Bearer <token>, or a similar header. Other requests will be rejected with 403.

For example:

auth_token("dGVzdF9zZWdlskfoe0aF90b2tlbg==")

include_request_headers()

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()

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<HOST>.*) 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<HOST>.*)"])

port()

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.

prefix()

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 for details). To avoid such problems, use a prefix when naming the parsed values, for example, prefix(my-parsed-data.)

proxy_header()

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()

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. 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()

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()

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()

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()

Description: Verification method of the peer. The following table summarizes the possible options and their results depending on the certificate of the peer.

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.

tls_use_system_cert_store()

Description: Use the certificate store of the system for verifying HTTPS certificates. For details, see the curl documentation.