/
ALERT: Webhook

ALERT: Webhook

Webhook is a user-defined HTTP callback that allows one system or application to send real-time data to another system or application as soon as an event occurs.

Instead of the traditional polling mechanism where one system repeatedly checks another for updates, a webhook enables real-time data delivery.

Webhook Integration—Payload Guide
This guide explains what data you will receive from the webhook integration and how to reliably parse it.

Payload Format:
Webhook events are sent via HTTP POST in JSON format:


{
"subject": "Event Summary / Category Name",
"body": "Event Description (detailed information about the event)"
}

Field Description:

  1. subject
    Represents the event category or title.
    This field is consistent and should be used as the primary routing key in your parser (for example: Critical Vulnerabilities Found, New Asset(s) Added, Login Failure).

  2. body
    Contains the detailed, human-readable description of the event.
    The content varies by event type and may include asset details, user information, vulnerabilities, timestamps, or system context.

Parsing Considerations:

  1. The JSON structure is always consistent (subject, body).

  2. The body field may contain multi-line text.

  3. Some details may be optional depending on availability.

Common Event Examples:

  1. Asset Events
    {
    "subject": "New Asset(s) Added",
    "body": "New asset added with ip 192.168.1.100. Hostname server-01.example.com. Mac address 00:1B:44:11:3A:B7"
    }

  2. Port Discovery Events
    {
    "subject": "Asset Ports",
    "body": "Open Port 443 Discovered for Asset 192.168.1.100, hostname server-01.example.com"
    }

  3. Vulnerability Events
    {
    "subject": "Critical Problems Found",
    "body": "Critical vulnerabilities detected for asset with IP 192.168.1.100, hostname server-01.example.com in company Acme Corporation\ Product: Apache HTTP Server. VUL ID: CVE-2021-44228. Severity: Critical"
    }

  4. Authentication / Audit Event
    {
    "subject": "Login Failure",
    "body": "Login Failure for john.doe With IPAddress 203.0.113.10 on service AzureAD at 2024-01-15 10:30:00 UTC"
    }

Recommended Parser Flow:

  1. Parse the JSON payload.

  2. Route logic based on the subject.

  3. Extract relevant fields from body.

  4. Store the full body as a raw message for traceability and future compatibility.

Below is a webhook event example text to see what alerts may look like:

Webhook URL, username, password, header key, and header value data will vary depending the exact webhook/system you are using. If you need help on your specific integration setup, please get in touch with our support team by emailing to support@connectsecure.com and provide the details and system(s) used.

Overview

This integration allows you to send data to your webhook based on the Event Sets and Integration Rules that are defined and mapped to a company.

For a full listing of the available Event Set alerting options, see Event Sets for Integration Alerting.

Getting Started

Navigate to Global > Settings > Integrations and tap on the Webhook tile.

image-20250917-142959.png

Setup

Credentials

You need to provide the required details as shown below.

image-20240607-185318.png

Field Label

Description

Field Label

Description

Name

A name of your choosing, to describe the webhook

Webhook URL

The main URL of the webhook; should include https://

Webhook Authentication URL

The authentication URL; should include https://

Webhook Username

Username

Webhook Password

Password

Authentication Header Key

The header_key defines the name of the header (e.g., Authorization, X-API-Key).

Authentication Header Value

The header_value contains the credential or token used for authentication.
These headers are added to the request at runtime and must be validated by the receiving service.

Selected Associated Companies

Select the ConnectSecure company or companies to use the webhook integration

Event Set

You will not see the Event Set, Integration Rules, or Company Mapping options until you have successfully saved and authenticated the webhook Credentials tab.

This is where you tell the integration what events should generate an alert. Tap the Add button to view and add your desired event sets.

image-20240607-185252.png

Give the Event Set a name of your choosing, select a Notify By option, and select the Event Set(s) you want to create the alert(s) for.

image-20240607-185229.png

Tap on the Category name (expand style menu) to see the individual Event Sets based on Category.

image-20240607-185205.png

Use the checkboxes to select the Event Sets, then tap the Save button. Upon doing so, you will be prompted with a Confirmation box asking if you want to create an Integration Profile or save your event set.

image-20240105-200305.png

Integration Rules

Here, you will create a name of your choosing and link the previously created Event Set. Tap Save to finish.

image-20240607-185019.png

You will be prompted with a Confirmation message to save the Integration Rule or tap Yes to save and move to the Company Mapping section.

image-20240105-210950.png

Company Mapping

This is where you map your ConnectSecure company to the Integration Rule(s) and can enable the ‘Create Webhook Alert’ box to enable this rule.

image-20240607-185100.png

Upon saving, the Selected Companies section appears with your mapping selection(s).

image-20240607-185124.png

Tap Finish to complete the setup.

If you receive an “Error Sending Request for URL” message after tapping Finish, please review the Whitelisting Documentation.

https://cybercns.atlassian.net/wiki/x/ZwDXhw