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. Create a new connector.

    1. Find the host.

    2. Select Connectors. The list of connectors available on the host is displayed.

      Connectors of the host

    3. Select add , then select the type of connector you want to create.

      Connectors of the host

    4. Enter a Name for the connector. This name must be unique on the host.

      Connectors of the host

    5. (Optional) Add custom labels to the connector.

      You can also modify the product and vendor labels of the connector. In that case, Axoflow will treat the incoming messages as it was received and classified as data from the specified product. This is useful if you want to send data from a specific product to a dedicated port.

      These labels and other parameters of the connector will be available under the meta.connector key as metadata for the messages received via the connector, and can be used in routing decisions and processing steps. You can check the metadata of the messages using log tapping.

      Connectors of the host

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

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

  4. 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.

  5. 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.

  6. Select Create.

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

  8. 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"}