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.

Prerequisites

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

• Key: The key file must contain an unencrypted private key in PEM or DER format, suitable as a TLS key. The Axoflow application uses this private key and the matching certificate to encrypt the communication with the client.
• Certificate: The file must contain an X.509 certificate (or a certificate chain) in PEM or DER format, suitable as a TLS certificate, matching the private key set in the Key option. If the file contains a certificate chain, the file must begin with the certificate of the AxoRouter host, followed by the CA certificate that signed the certificate of the host, and any other signing CAs in order.

Add new webhook connector

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

1. Select Connectors > Create new rule. (Alternatively, you can select Add Connector > Create 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 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.

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

      

      • If you leave the Router Selector field empty, the rule will match every AxoRouter instance.
      • To select only a specific AxoRouter instance, set the name field with the name of the instance as selector.
      • If you set multiple fields in the selector, the connector rule will apply only to 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. This suffix will be used in the name of the connector instances created on the AxoRouter hosts. For example, if the name of a matching AxoRouter instance is “my-axorouter”, and the suffix of the rule is “otlp-rule”, the connector created for the AxoRouter will be named “my-axorouter-otlp-rule”.

      If the Suffix field is empty, the name of the connector rule is used instead.

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

4. Select the protocol you want to use: HTTPS or HTTP.

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

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 Key and the Certificate files. AxoRouter uses these to encrypt the TLS channel. You can use absolute paths (for example, /etc/axorouter/user-config/tls-key.pem). The key and the certificate must be in PEM format.

   You must manually copy these files to their place, currently you can’t distribute them from Axoflow.

8. Select Create.

   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: