Generic Webhook¶

Cyderes has developed a generic webhook collector to support the ingestion of data from log sources that support webhooks.

Cyderes will provide an API key, URL, and data type to use when setting up the webhook. The api key and URL can be used by multiple log sources, meaning any system that supports webhooks can use the same API key and URL to pass data to the collector. However, the data types will likely be different for each log source (see below for more information on data types).

Authentication¶

Authentication is handled by passing a Cyderes provided API Key in either the header or query parameters of the request.

To pass the API Key via a header, set the Authorization header to Authorization: <API_KEY> where the API Key is replaced by the key provided by Cyderes.
To pass the API Key via a query parameter, set the query to api_key=<API_KEY> NOTE: Ensure the API Key is URL encoded when passing it via a query parameter.

Data Types¶

Similar to authentication, data types can be passed to the webhook through either header values or query parameters.

To pass in a data type via a header, add LogType: <DATA_TYPE> to the headers of the request
To pass in a data type via a query parameter, set the query to log_type=<DATA_TYPE>

In both cases, the data type is the Chronicle data type for the log source. Cyderes will assist in determining the data type to use for a log source.

Labels¶

Labels are optionally passed to the webhook through either header values or query parameters.

To pass in a label via a header, add X-Cyderes-Labels-<LABEL_KEY>: <LABEL_VALUE> to the headers of the request
To pass in a label via a query parameter, set the query to x_cyderes_labels_<LABEL_KEY>=<LABEL_VALUE>

Header values will take precedence over query parameters in the instance that labels with the same key are passed via both a header value and a query parameter.

In Chronicle, these labels will be surfaced as metadata.ingestion_labels on parsed logs. For instance:

metadata.ingestion_labels[0].key: "label_key"
metadata.ingestion_labels[0].value: "label_value"

Endpoints¶

Each webhook that is deployed has three endpoints however, two of those are deprecated. The newest endpoint is meant to replace the other two to simplify receiving data. This new endpoint, however, does rely on the proper Content-Encoding and Content-Type headers to be able to process the data so ensure that both are accurate for the data being passed in request bodies.

V2¶

Webhook endpoint¶

This endpoint is meant to be smart about how it handles logs https://<Cyderes_Provided_URL>/collector/v2/webhook

This endpoint can support various content types.

plain/text¶

For plain text, currently only newline delimited bodies are supported where each line corresponds to a new line

log1 this is a message
log2 this is a message
log3 this is a message

application/json¶

JSON and NDJSON/JSONL are supported.

NDJSON/JSONL¶

{"metadata":{"eventTime":"1970-01-01T00:00:00.000Z","eventType":"Event"}}
{"metadata":{"eventTime":"1970-06-01T00:00:00.000Z","eventType":"Event"}}
{"metadata":{"eventTime":"1970-06-01T00:00:00.000Z","eventType":"Event"}}

JSON (Array of logs)¶

[
  {"metadata":{"eventTime":"1970-01-01T00:00:00.000Z","eventType":"Event"}},
  {"metadata":{"eventTime":"1970-06-01T00:00:00.000Z","eventType":"Event"}},
  {"metadata":{"eventTime":"1970-06-01T00:00:00.000Z","eventType":"Event"}}
]

JSON (Single log)¶

{
    "metadata": {
        "eventTime": "1970-06-01T00:00:00.000Z",
        "eventType": "Event"
    }
}

V1 (DEPRECATED)¶

Single Log Endpoint¶

For a single log, the endpoint is https://<Cyderes_Provided_URL>/collector/webhook

This endpoint expects a single JSON formatted body with no new lines e.g.

{"data":"some data"}

Batch Endpoint¶

For batch logs, the endpoint is https://<Cyderes_Provided_URL>/collector/batch

This endpoint expects a JSON array of data e.g.

[{"data":"some data"},{"data":"more data"}]

Examples¶

The following examples are using curl to show how request headers and query parameters should be formatted. Make sure to replace the Cyderes provided URL, API key, and data type with the values provided by Cyderes before sending a test request.

Query Parameter Values Request¶

curl --request POST \
  --url 'https://<Cyderes_Provided_URL>/collector/v2/webhook?api_key=<API_KEY>&log_type=<DATA_TYPE>&x_cyderes_labels_<LABEL_KEY>=<LABEL_VALUE>' \
  --header 'Content-Type: application/json' \
  --data '{"data": "some data"}'

curl --request POST \
  --url 'https://<Cyderes_Provided_URL>/collector/batch?api_key=<API_KEY>&log_type=<DATA_TYPE>&x_cyderes_labels_<LABEL_KEY>=<LABEL_VALUE>' \
  --header 'Content-Type: application/json' \
  --data '[{"data": "some data "},{"data": "more data"}]'

Header Values Request¶

curl --request POST \
  --url 'https://<Cyderes_Provided_URL>/collector/v2/webhook' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: <API_KEY>' \
  --header 'LogType: <DATA_TYPE>' \
  --header 'X-Cyderes-Labels-<LABEL_KEY>: <LABEL_VALUE>' \
  --data '{"data": "some data"}'

curl --request POST \
  --url 'https://<Cyderes_Provided_URL>/collector/v2/webhook' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: <API_KEY>' \
  --header 'LogType: DATA_TYPE' \
  --header 'X-Cyderes-Labels-<LABEL_KEY>: <LABEL_VALUE>' \
  --data '[{"data": "some data"},{"data": "more data"}]'