Webhook Collector
The Webhook Collector microservice receives payloads in HTTP requests from various vendors to a custom endpoint. It converts the payloads to JSON, adding metadata and contextual information, and wraps them in a Unified Assurance JSON wrapper to ensure a standard structure. The transformed payload is then published to the configured Apache Pulsar topic.
This microservice is a supporting microservice that can participate in any microservice pipeline. See Understanding Microservice Pipelines in Unified Assurance Concepts for conceptual information about microservice pipelines.
This microservice provides additional Prometheus monitoring metrics. See Webhook Collector Self-Monitoring Metrics.
Webhook Collector Prerequisites
Before deploying the microservice, confirm that the following prerequisites are met:
-
A microservice cluster is set up. See Microservice Cluster Setup.
-
The Pulsar microservice is deployed. See Pulsar.
-
(Optional) You can create a Kubernetes secret containing the SSL certificate by doing the following as the assure1 user:
-
Create a PKCS #12 certificate:
openssl pkcs12 -export -passout pass:<password> -in <path_to_cert_file> -inkey <path_to_key_file> -out <output_file_name>.p12 -name <name> -
Create the secret:
export NAMESPACE=<namespace> a1k create secret generic webhook-ssl-cert --from-file=<path_to_p12_cert> -n $NAMESPACEwhere:
-
<namespace> is the namespace where you are deploying the microservice. The default namespace is a1-zone1-pri, but you can change the zone number and, when deploying to a redundant cluster, change pri to sec.
-
<path_to_p12_cert> is the path to the .p12 certificate that you created.
-
-
Deploying Webhook Collector
To deploy the microservice, run the following commands:
su - assure1
export NAMESPACE=<namespace>
export WEBFQDN=<WebFQDN>
a1helm install <microservice-release-name> assure1/webhook-collector -n $NAMESPACE --set global.imageRegistry=$WEBFQDN
In the commands:
-
<namespace> is the namespace where you are deploying the microservice. The default namespace is a1-zone1-pri, but you can change the zone number and, when deploying to a redundant cluster, change pri to sec.
-
<WebFQDN> is the fully-qualified domain name of the primary presentation server for the cluster.
-
<microservice-release-name> is the name to use for the microservice instance. Oracle recommends using the microservice name (webhook-collector) unless you are deploying multiple instances of the microservice to the same cluster.
You can also use the Unified Assurance UI to deploy microservices. See Deploying a Microservice by Using the UI for more information.
Changing Webhook Collector Configuration Parameters
When running the install command, you can optionally change default configuration parameter values by including them in the command with additional --set arguments. You can add as many additional --set arguments as you need.
For example, set a parameter described in Default Webhook Collector Configuration by adding --set configData.<parameter_name>=<parameter_value>. For example, --set configData.LOG_LEVEL=DEBUG.
Default Webhook Collector Configuration
The following table describes the default configuration parameters found in the Helm chart under configData for the microservice.
| Name | Default Value | Possible Values | Notes |
|---|---|---|---|
| LOG_LEVEL | INFO | FATAL, ERROR, WARN, INFO, DEBUG | The logging level used by the microservice. |
| STREAM_OUTPUT | "persistent://assure1/event/collection" | Text | The Pulsar topic to send messages to. |
| WEBHOOK_ENDPOINT | "/webhook" | Text | The endpoint exposed to receive messages. |
| WEBHOOK_KEYSTORE | "" | Text | Name of the PKCS12 certificate file. Kubernetes secret containing SSL certificate must be created (prerequisites point 3). |
| KEYSTORE_PASSWORD | "" | Text | Keystore password to be used when using SSL certificate. |
Webhook Collector Self-Monitoring Metrics
The Webhook Collector microservice exposes the self-monitoring metrics described in the following table to Prometheus.
| Metric Name | Type | Description |
|---|---|---|
| webhook_received_payload_count | Counter | The total number of payloads received on the webhook. |
| webhook_to_pulsar_payload_count | Counter | The total number of payloads sent to Pulsar. |
| total_errors_occurred | Counter | The total number of errors occurred in the webhook. |
Note:
Metric names in the database include a prefix that indicates the service that inserted them. The prefix is prom_ for metrics inserted by Prometheus. For example, total_errors_occurred is stored as total_errors_occurred in the database.
About Webhook Collector Transformations
The Webhook Collector microservice accepts the following Content-Type for input HTTP request payloads:
-
application/json
-
application/xml
-
application/x-www-form-urlencoded
-
text/plain
-
application/x-yaml
When the microservice converts these payloads to JSON, it adds the following fields:
-
domain: The event domain. For webhook events, this is fault.
-
@timestamp: The time the message was processed by the Webhook Collector.
-
webhook: The input payload content and headers.
-
headers: The request REST headers and details about the endpoint and query parameters.
-
endpoint: The endpoint to which the request was made, prefixed by the configured endpoint path.
-
queryParams: Any request query parameters.
-
ZoneId: The zone ID associated with the namespace where the event originated.
-
content: The request payload, converted to JSON format. If JSON conversion is not possible, the raw form is shown.
-
rawContent: The payload exactly as it was received, in its original raw format.
-
-
_type: The type of event. For webhook events, this field is set to webhook.
-
source: The IP and DNS details of the message's origin.
-
agents: The details of the Webhook Collector instance that collected the message, useful for backtracking and auditing.
-
_version: The version of the Unified Assurance wrapper.
About Custom FCOM Rules for Webhook Events
You primarily use Webhook Collector to send messages to the FCOM Processor, which further normalizes the payloads into the standard Unified Assurance event structure and sends them to the Event Sink microservice for insertion into the Event database. You can optionally create custom FCOM rules to process webhook events in custom ways according to your environment and needs.
The rules must set method to webhook, and can use webhook as a key to specify additional fields that must appear in the event for the rules to be applied. The default FCOM rules for the Aruba Central Poller microservice show an example of using the webhook method and key. You can see the rules by expanding the following folders in the Rules UI:
Core Rules (core)/Default read-write branch (default)/processing/event/fcom/_objects/aruba
See FCOM Processor, About FCOM Rules for Custom Events, and Fault for more information.