# Collect data using HTTP {% hint style="info" %} * See the changelog of the **HTTP** Listener type [here](/listeners/http-listener.md). * See the changelog of the **HTTP Standard Inbound** Listener [here](/listeners/http-standard-inbound-listener.md). {% endhint %} ## 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](https://docs.onum.com/usecases/routing/crowdstrike-integration/self-signed-ssl-tls-certificates-creation). * 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**.** {% stepper %} {% step %} Log in to your Onum tenant and click **Listeners > New listener**. {% endstep %} {% step %} Double-click the **HTTP/HTTP Standard Inbound** Listener. {% endstep %} {% step %} Enter a **Name****\*** for the new Listener. Optionally, add a **Description** and some **Tags** to identify the Listener. {% endstep %} {% step %} 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. {% endstep %} {% step %} 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](https://docs.onum.com/usecases/routing/crowdstrike-integration/self-signed-ssl-tls-certificates-creation). Once you have them, click **New secret** in each field and add the corresponding values. {% endstep %} {% step %} 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](/administration/tenant-menu.md).
Bearer Enter your **Token Secret** for the API request using an existing Secret or [creating a new one](/administration/tenant-menu.md) 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](/administration/tenant-menu.md) 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](/administration/tenant-menu.md) if you haven't stored this key within Onum.
{% hint style="info" %} Learn more about secrets in Onum in [this article](/administration/global-settings/organization-settings/secrets-management.md). {% endhint %} {% endstep %} {% step %} 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. {% endstep %} {% step %} 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. {% endstep %} {% step %} 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). {% endstep %} {% step %} 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. {% endstep %} {% step %} **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](#download-certificate)). {% hint style="info" %} You can access all this information in the Listener details after creation, so don't worry. {% endhint %} * If you entered the TLS certificates, you'll go directly to the **Labels**. {% endstep %} {% step %} 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. {% hint style="info" %} Learn more about labels in [this article](/the-workspace/listeners/labels.md). {% endhint %} {% endstep %} {% endstepper %} ## 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**. {% hint style="info" %} This .p12 does not require password to access. {% endhint %} 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. {% hint style="warning" %} 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. {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.onum.com/the-workspace/listeners/listener-integrations/collect-data-using-http.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.