Skip to content

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>

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 two endpoints. One for accepting single log events, and one for accepting a batch of log events. Both sources expect data to come in formatted as JSON in the body of a POST http request.

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/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/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/batch' \
  --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"}]'