Webhook

Webhook connectors of AxoRouter can be used to receive log events through HTTP(S) POST requests.

You can specify static and dynamic URLs to receive the data. AxoRouter automatically parses the JSON payload of the request, and adds it to the log.body field of the message as a JSON object. Other types of payload (including invalid JSON objects) is added to the log.body field as a string. Note that you can add further parsing to the body using processing steps in Flows, for example, using FilterX or Regex processing steps.

If your clients send several events in a single request (for example, line-separated records or concatenated JSON objects), use a Generic HTTP connector instead. Generic HTTP connectors split the body of the request into separate messages.

Prerequisites

To receive data via HTTPS, you’ll need a key and a certificate that the connector will show to the clients.

If you want to enable TLS encryption for this connector to encrypt the communication with the sources, you’ll need to set appropriate keys and certificates.

Note the following points:

• Keys and certificates must be in PEM format.
• 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.
• If you manually copy these files to their place on the AxoRouter host, make the files readable by the axorouter service.
  • The recommended path for certificates is under /etc/axorouter/user-config/ (for example, /etc/axorouter/user-config/tls-key.pem). (If you need to use a different path, you have to append an option like -v /your/path:/your/path to the AXOROUTER_PODMAN_ARGS variable of /etc/axorouter/container.env.)
  • When referring to the key or certificate when configuring the connector, use absolute paths (for example, /etc/axorouter/user-config/tls-key.pem).

Add new webhook connector

To add a new connector to an AxoRouter host, complete the following steps:

1. Select Routers > Connector Rules > Add Connector Rule. (Alternatively, you can select Add Connector > Add a connector rule on the Connectors page of an AxoRouter host.)

   

2. Select Webhook.

3. Configure the connector rule.

   1. Enter a name for the connector rule into the Connector rule name field.

      

   2. (Optional) Add labels to the connector rule. You will be able to use these labels in Flow Processing steps, for example, in the Query field of Select Messages steps. For details about the message schema and the related connector-specific fields, see the meta.connector object.

   3. Set the Router selector for the connector rule. The selector determines which AxoRouter instances will have a connector based on this connector rule.

      

      You can use any labels and metadata of the AxoRouter hosts in the Router selectors, for example, the hostname of the AxoRouter, or any custom labels.

      • If you leave the router selector empty, it matches every AxoRouter instance.
      • To select only a specific AxoRouter instance, set the name field to the name of the instance as selector. For example, name = my-axorouter.
      • If you set multiple fields in the selector, the selector will match only AxoRouter instances that match all elements of the selector. (There in an AND relationship between the fields.)

   4. (Optional) Enter a Suffix for the connector rule. AxoConsole uses the suffix in the name of the connector instances that it creates on the AxoRouter hosts. The name of the connector instance follows the <name-of-AxoRouter>-<suffix> schema. For example, if the name of a matching AxoRouter instance is axorouter-1, and the suffix of the rule is custom, the name of the connector on that AxoRouter is axorouter-1-custom.

      If the Suffix field is empty, AxoConsole uses the name of the connector rule instead. For example, if the name of the connector rule is otlp-1, the name of the connector is axorouter-1-otlp-1.

   5. (Optional) Enter a description for the rule.

   6. If needed, turn on the Classify and Parse steps in the Preprocessing steps section (they’re off by default), so AxoRouter automatically identifies and parses messages sent by supported data sources. If your source is not listed, contact us.

      Enabling these options processes all data received by the connectors created based on this connector rule. If you want to apply classification and parsing more selectively, you can use the Classify and Parse processing steps in your Flows.

      Note that the Parse processing step requires Classify to be enabled. Parsing automatically parses the data from the content of the message, and replaces the message content (the log.body field in the internal message schema) with the structured information.

   7. (Optional) If needed, you can add other preprocessing steps to the connector rule. You can use the same processing steps as in flows. These can be useful if you use a dedicated connector rule to fix or annotate data coming from some specific sources. To reuse the preprocessing steps in other connector rules or flows, select Save as Custom Step.

4. In the Schema field, select the protocol you want to use: HTTP or HTTPS.

   

5. Set the port number where the webhook will receive the POST requests, for example, 8080.

   CAUTION:

   TCP and UDP port range 29500–29519 is reserved for AxoRouter’s internal listeners and cannot be used in connector rules.

6. Set the endpoints where the webhook will receive data in the Paths field. You can use static paths, or regular expressions. In regular expressions you can use named capture groups to automatically set macro values in AxoRouter. 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.

   By default, the /events and /events/(?P<HOST>.*) paths are active.

7. For HTTPS endpoints, set the path to the Server certificate and the Server private key options. AxoRouter uses these to encrypt the TLS channel.

   Note These settings apply to every AxoRouter that matches the Router selector of the connector rule. If you paste values for the server certificate and server private key, every matching AxoRouter uses the same shared certificate, which is not recommended. Instead, use a separate certificate for each AxoRouter by setting the file path option, or create a separate connector rule for each AxoRouter.

   • Server certificate: The certificate that AxoRouter shows to the clients.

     • To provide the server certificate from the AxoConsole, select Paste value and paste the server certificate. AxoConsole will automatically deploy the server certificate to the related AxoRouters.
     • To provide the server certificate from a file, select File path and enter the path where the certificate file is located (for example, /etc/axorouter/user-config/server-certificate.pem). The path must be mounted into the container, /etc/axorouter is mounted by default. You must manually copy that file to its place on every affected AxoRouter, or you can use the configuration management system of your choice.

   • Server private key: The private key of the server certificate.

     • To provide the server private key from the AxoConsole, select Paste value and paste the server private key. AxoConsole will automatically deploy the server private key to the related AxoRouters.
     • To provide the server private key from a file, select File path and enter the path where the private key file is located (for example, /etc/axorouter/user-config/server-private-key.pem). The path must be mounted into the container, /etc/axorouter is mounted by default. You must manually copy that file to its place on every affected AxoRouter, or you can use the configuration management system of your choice.

8. Select Add.

   Axoflow automatically creates connectors on the AxoRouter hosts that match the Router selector.

   Make sure to enable the ports you’ve configured in the connector on the firewall of the AxoRouter host, and on other firewalls between the AxoRouter host and your data sources.

9. Send a test request to the webhook.

   1. Open the Overview tab of the AxoRouter host where you’ve created the webhook connector and check the IP address or FQDN of the host.

   2. Open a terminal on your computer and send a POST request to the path you’ve configured in the webhook.

      curl -X POST -H 'Content-Type: application/json' --data '{"host":"myhost", "body": "sample webhook message" }' <router-IP-address>:<webhook-port-number>/<webhook-path>/

      For example, if you’ve used the default values of the webhook connector you can use:

      curl -X POST -H 'Content-Type: application/json' --data '{"host":"myhost", "body": "sample webhook message" }' <router-IP-address>/events/

      Expected output:

      {"status": "received"}

Note You can also use Log tapping on the AxoRouter host to see the incoming messages.

Metadata fields

The AxoRouter webhook connector adds the following fields to the meta variable:

You can use the labels as:

• labels in Customize Graph on the Analytics page,
• in the Filter labels field during log tapping.

You can use the message fields

• in Flow Processing steps, for example, in the Query field of Select Messages steps,
• in AQL expressions in the search bars.