# HTTP Source

## Overview

Using Panther's HTTP log ingestion capability, you (or a third party) can send log events directly to Panther with webhooks. When you create an HTTP log source, Panther provides a URL endpoint to which you can make POST requests containing data for ingestion.

For log sources without a direct API puller, using an HTTP source means you can ingest data into Panther without setting up additional infrastructure (as is required with other [Data Transports](https://docs.panther.com/~/changes/15ann7vKLltCCAGHtdQr/data-onboarding/data-transports), such as [S3](https://docs.panther.com/~/changes/15ann7vKLltCCAGHtdQr/data-onboarding/data-transports/aws/s3) or [Google Cloud Storage](https://docs.panther.com/~/changes/15ann7vKLltCCAGHtdQr/data-onboarding/data-transports/google/cloud-storage)).

## Payload requirements

When sending data to Panther through an HTTP endpoint, note the following specifications.

### Maximum size

The maximum supported payload size is 1 MB.

### Stream types

Panther supports the below three stream types for data ingested through an HTTP source:

* JSON (default)
* Lines
* JSON Array

See a [description and example of each stream type here](https://docs.panther.com/~/changes/15ann7vKLltCCAGHtdQr/custom-log-types/reference#stream-type).

### Compression

Payloads can be sent compressed (or uncompressed). Learn more about compression specifications in [Ingesting compressed data in Panther](https://docs.panther.com/~/changes/15ann7vKLltCCAGHtdQr/data-onboarding/data-transports/..#ingesting-compressed-data-in-panther).

## Authentication

To secure your HTTP endpoint, ensuring it only processes requests from authenticated sources, Panther offers the following modes of authentication:

### **Shared secret**

With shared secret authentication (also known as token authentication), you configure a header name and shared secret value during source setup. The entity making the POST request to Panther must include a header with that name and secret value. Panther will only accept payloads with headers and secrets that match your configuration.

This method is referred to as shared secret because the secret is shared between Panther and the entity making the POST request, e.g., a third-party SaaS tool emitting log events.

### HMAC

With HMAC authentication, you configure a header name and secret key value during source setup. The entity making the POST request to Panther must hash the payload of each request, use the secret key value to generate a signature, and include that signature in a header. Panther will then retrieve the signature from the header and perform the same signature calculation using the secret key. Only requests with matching signatures will be accepted.

### Bearer

With bearer authentication, you define a bearer token value during source setup. The entity making the POST request to Panther must include a header of the format `Authorization: Bearer tokenvaluehere`. Panther will only accept request with matching bearer tokens.

### Basic

With basic authentication, you define a username and password during source setup. The entity making the POST request to Panther must include a header of the format `Authorization: Basic aGVsbG8=`. The string after the `Basic` keyword follows [RFC 7617](https://datatracker.ietf.org/doc/html/rfc7617#section-2), meaning the sender must encode the value of `username:password` using base64. Panther only accepts requests with a matching username and password.

### **None**

While highly discouraged, it is possible to configure an endpoint without authentication. This means Panther will not perform *any* authentication checks on incoming requests, effectively making your URL open to all POST requests.

It is strongly recommended to set up authentication on your endpoint. **None** is offered for situations in which you do not have control over the headers provided by the sender.

## How to set up an HTTP log source in Panther

To set up an HTTP log source in Panther, follow the steps below. You can also view the [data ingestion video overview](https://docs.panther.com/~/changes/15ann7vKLltCCAGHtdQr/data-onboarding/..#video-overview) for a quick walkthrough of HTTP source setup.

### Prerequisite

* Before starting setup for your HTTP log source, ensure there is a schema for your incoming logs. You will need to select one or more schemas (or "Log Types") during HTTP source creation. See the [instructions for creating a custom schema here](https://docs.panther.com/data-onboarding/custom-log-types#how-to-define-a-custom-schema).

### Creating the HTTP log source in Panther

1. In the left-hand navigation bar of your Panther Console, click **Configure** > **Log Sources**.
2. In the upper-right corner, click **Create New.**
3. Click the **Custom Log Formats** tile.
4. In the **HTTP** tile on the slide-out panel, click **Start**.\
   ![In the Custom Log Formats slide-over panel, an arrow is pointing to the "Start" button in the "HTTP" tile. There are various other tiles, such as "AWS S3 Bucket," and "Azure Blob Storage."](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2FrCTwLzYG8rOvLstbWOPK%2FScreenshot%202023-05-30%20at%204.06.28%20PM.png?alt=media\&token=837cde82-6317-45f8-b452-f86ec0a5e2da)
5. On the **Configure** page, provide values for the following fields:
   * **Name**: Enter a descriptive name for the source.
   * **Log Types**: Select one or more log types this source will ingest.
   * **Stream Type**: Choose between **Lines**, **JSON**, and **JSON Array.**\
     ![On the Configure page of HTTP source setup, there are fields for Name, Log Types, and Log Stream Type.](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2FUcbltiNgUeZdfRPqgS31%2FScreenshot%202023-06-20%20at%204.31.14%20PM.png?alt=media\&token=b4f9623e-38cc-4dd2-8db5-ceb213244e38)
6. Click **Setup**.
7. On the **Security** page, select an **Auth method** based on your chosen [mode of authentication](#authentication)**.**\
   ![Under an Authentication header is the question: How would you like Panther to authenticate data sent to this log source? Then, in an open dropdown menu, are five options: Shared Secret, HMAC, Bearer, Basic, None](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2FtCGi5dDQ8fCja0RV4zGo%2FScreenshot%202023-05-01%20at%203.17.02%20PM.png?alt=media\&token=3620e2cb-e3a0-40a4-97f1-07946c38d33a)
8. Follow the instructions below for the **Auth method** you chose:
   * **Shared Secret**: Enter a **Header Name**, and generate a **Shared Secret Value**.
     * Securely copy your **Shared Secret Value**, and store it in a safe location. This is the only time you will be shown the **Shared Secret Value**.
   * **HMAC**: Enter a **Header Name**, generate a **Secret Key Value**, and choose a **Hashing Algorithm** (either **SHA 256** or **SHA 1**). 
     * Securely copy your **Secret Key Value**, and store it in a safe location. This is the only time you will be shown the **Secret Key Value**.
   * **Bearer**: Enter a **Bearer Token**.
     * In the value you enter, do not include "Bearer."
     * Be sure to securely store your **Bearer Token** value. It will not be visible in the Panther Console.
   * **Basic**: Enter **Username** and **Password** values.
     * Be sure to securely store your **Password** value. It will not be visible in the Panther Console.
   * **None**: No additional configuration required.
9. Click **Setup**. You will be directed to a success screen:<br>

   <figure><img src="https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2FMTRmOqjJY878NPgsMe1B%2FScreenshot%202023-08-03%20at%204.33.30%20PM.png?alt=media&#x26;token=7cf48278-6e1f-455a-81aa-2d76388fbfa8" alt="The success screen reads, &#x22;Everything looks good! Panther will now automatically pull &#x26; process logs from your account&#x22;" width="281"><figcaption></figcaption></figure>

   * Take note of your **HTTP Source URL**. Webhooks should make POST requests to this endpoint.
   * You can optionally enable one or more [Detection Packs](https://docs.panther.com/detections/panther-managed/packs).
   * The **Trigger an alert when no events are processed** setting defaults to **YES**. We recommend leaving this enabled, as you will be alerted if data stops flowing from the log source after a certain period of time. The timeframe is configurable, with a default of 24 hours.<br>

     <figure><img src="https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2FyXM7rz58X1m3iNo3w69h%2FScreenshot%202023-08-03%20at%204.26.54%20PM.png?alt=media&#x26;token=586be93d-b2a0-4c03-aa07-098fbc524000" alt="The &#x22;Trigger an alert when no events are processed&#x22; toggle is set to YES. The &#x22;How long should Panther wait before it sends you an alert that no events have been processed&#x22; setting is set to 1 Day" width="320"><figcaption></figcaption></figure>

## Sending data to your HTTP log source

After creating your HTTP log source, you can use it to send data to Panther by making POST requests to the source URL.

Ensure your request passes the [authentication method](#authentication) you configured for the source.

### Example using `curl`&#x20;

```sh
curl --data '{ "hello": "world" }' \
    -H "x-custom-secret: mysecret" \
    https://{YOUR_URL}
```