Collect data using HTTP

• See the changelog of the HTTP Listener type here.

• See the changelog of the HTTP Standard Inbound Listener here.

Overview

Use the HTTP Listener to listen for HTTP requests.

If your source does not support mutual TLS (mTLS) encryption, use the HTTP Standard Inbound Listener for TLS encryption without requiring mTLS. We always recommend using mTLS encryption for maximum security.

The steps to set up the HTTP Standard Inbound Listener are the same as below, so you can follow this article.

Important Considerations Regarding Cloud Deployments

• In cloud-based Onum installations, the TLS configuration section of the HTTP Listener is not visible and you won't need to enter these values. In these setups, Onum automatically manages TLS certificates, eliminating the need for manual configuration. If your HTTP Listener configuration requires you to manually enter these TLS certificates, you can generate them following the instructions in this article.

• If you are defining this Listener in a cloud instance, Onum will automatically provide the Port and TLS configuration (mTLS for the HTTP Listener, TLS for HTTP Standard Inbound Listener).

• In cloud deployments, these Listeners have an additional step in their creation process: Network configuration. Use these details to configure your data source to communicate with Onum. Click Download certificate to get the required certificate for the connection. You can also download it from the Listener details once it is created.

• When configuring a Listener in a cloud tenant, the port will always be 443. In on-prem deployments, the selected port must fall within the range of 1024 to 10000.

• In cloud deployments, endpoints are created in Onum's DNS. This process is usually fast, and Listeners are normally available immediately. However, note that this may last up to 24-48 hours, depending on your organization's DNS configuration.

• Your data input must use the Server Name Indication (SNI) method, which means it must send its hostname in the TLS authentication process. If SNI is not used, the certificate routing will fail, and data will not be received, even if the certificate is valid.

Onum Setup

Here we will detail the steps for the HTTP and HTTP Standard Inbound Listeners.

1

Log in to your Onum tenant and click Listeners > New listener.

2

Double-click the HTTP/HTTP Standard Inbound Listener.

3

Enter a Name* for the new Listener. Optionally, add a Description and some Tags to identify the Listener.

4

For most cloud-based Onum installations, the Socket section is not visible, and port 443 is used by default. If you see it, enter the required port in the Port* field. At this time, all TCP ports from 1024 to 10000 are open.

5

In most cloud-based Onum installations, the TLS configuration section is not visible. In these setups, Onum automatically manages TLS certificates, eliminating the need for manual configuration.

If you see this section, you must enter the required Certificate, Private key and CA Chain. Learn how to generate these self-signed certificates in this article. Once you have them, click New secret in each field and add the corresponding values.

6

If your connection does not require Authentication, leave the Authentication type* field as None. Otherwise, choose the authentication type and enter the details.

The options provided will vary depending on the type chosen to authenticate your API. This is the type you have selected in the API end, so it can recognize the request.

Basic

Enter the following:

• Username* - The user sending the request.

• Password* - Choose the basic auth password from your list of Secrets or create a new one.

Bearer

Enter your Token Secret for the API request using an existing Secret or creating a new one if you haven't stored it in Onum yet.

This grants access without needing to send credentials (like username and password) in every request.

Example

Let's say you have the following configuration:

• Port - 8080

• Authentication Type - Bearer

• Bearer Token Secret - a-string-secret-at-least-256-bits-long (This is the value you enter into Onum as the secret)

• Request path - localhost

When you listen for the HTTP request, the token will be encoded: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30

This entire request will show as follows: "http://localhost:8080/bearer" 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30'

API Key in URL Params

Enter the following:

• API Key Name* - A label assigned to the API key for identification. You can find it depending on where the API key was created.

• API Key Value* - API keys are usually stored in developer portals, cloud dashboards, or authentication settings. Choose the existing Secret or create a new one if you haven't stored this key within Onum.

Note that if you select this option, the HTTP Listener expects the API Key to be included in the URL, as a query parameter. For example:

curl --location 'http://customer.in.prod.onum.com:2250/test?My-Token=1234567890qwerty' \
--header 'Content-Type: application/json' \
--data '{"message": "hello, how are you doing? :)"}'

API Key in Header

Enter the following:

• API Key in Header Name* - A label assigned to the API key for identification. You can find it depending on where the API key was created.

• API Key in Header Value* - API keys are usually stored in developer portals, cloud dashboards, or authentication settings. Choose the existing Secret or create a new one if you haven't stored this key within Onum.

Learn more about secrets in Onum in this article.

7

In the HTTP method* field, choose GET, POST, or PUT method and the Request path* to the resource being requested from the server. The path starts with /, for example if the URL is https://localhost/onum, /onum is the path.

8

In the Message extraction section, the Strategy* defines how data extraction should be performed. It is the overall methodology or approach used to extract relevant information from HTTP messages. Choose between:

• Single event with the whole request - Choose this option if you want to include the whole request in each event.

• Single event from request path - Choose this option if you want to include the request paths in each event.

• Single event as query string - Choose this option if you want to include the requests with their whole query strings.

• Single event as query parameter - Choose this option if you want to include a specific request parameter in your events. Specify the required parameter name in the Extraction info option (for example: msg)

• Single event as header - Choose this option if you want to include a specific header in your events. Specify the required header in the Extraction info option (for example: Message)

• Single event as body (partially) - Choose this option if you want to include a part of the request body in your events. Specify the required RegEx rule to match the required part in the Extraction info option (for example: \\[BODY: (.+)\\])

• Single event as body (full) - Choose this option if you want to include the whole request body in your events. Specify the required RegEx rule to match the required part in the Extraction info option (for example: \\[BODY: (.+)\\])

• Multiple events at body with delimiter - Choose this option if you want to include several messages in the same event separated by a delimiter. You must specify the delimiter in the Extraction info option.

• Multiple events at body as JSON array - Choose this option if you want to include several messages formatted as a JSON array in your events.

• Multiple events at body as stacked JSON - Choose this option if you want to include several messages formatted as a stacked JSON in your events.

9

In the General behavior section, choose between None (default option), Allow (enter the required header keys below), or All (all headers will be retrieved in the headers field).

10

Then, configure the following settings:

• Header keys - Enter the required header keys in this field. Click Add element for each one.

• Exported headers format - Choose the required format for your headers. The default value is JSON.

• Maximum message length - Maximum characters of the message. The default value is 4096.

• Response code - Specify the response code to show when successful. The default value is 202 Accepted.

• Response Content-Type - The Content-Type: xxx/xxx lets the server know the expected format of the incoming message or request (application/json by default):

  • text/plain - The message body contains plain text.

  • application/json - The message body is formatted as JSON.

  • application/xml - The message body is formatted as XML.

  • text/html - The message body contains HTML.

• Response text - The text that will show in case of success.

11

Now there are two possible scenarios:

• If you didn't enter your TLS certificates, when you click Create listener you'll see the Network configuration screen, which shows the Address and Port needed to communicate with Onum. Here you will download the certificate (see the steps after creation to do this).

You can access all this information in the Listener details after creation, so don't worry.

• If you entered the TLS certificates, you'll go directly to the Labels.

12

Finally, click Create labels. Optionally, you can set labels to be used for internal Onum routing of data. By default, data will be set as Unlabeled. Click Create listener when you're done.

Learn more about labels in this article.

Download Certificate

if you have created an HTTP Listener in an Onum cloud deployment, you can download the certificate from the Listeners view by clicking the created Listener. In the details view, select the three dots in the top right-hand corner and click Download Certificate.

This .p12 does not require password to access.

To extract the certificates from the download, use the following command:

#!/bin/bash
# Extract certs from certificate.p12

# Client certificate (PEM)
openssl pkcs12 -in certificate.p12 -clcerts -nokeys -out client.crt -password pass:

# Client private key (PEM)
openssl pkcs12 -in certificate.p12 -nocerts -nodes -out client.key -password pass:

# CA chain (PEM)
openssl pkcs12 -in certificate.p12 -cacerts -nokeys -out ca-chain.crt -password pass:

Output Ports

The HTTP and HTTP Standard Inbound Listeners have two output ports:

• Default port - Events are sent through this port if no error occurs while processing them.

• Error port - Events are sent through this port if an error occurs while processing them.

The error message is provided in a free-text format and may change over time. Please consider this if performing any post-processing based on the message content.