How does the Webhooks integration work?

Webhook integrations allow Holm Security to automatically send real-time notifications to external systems whenever security events occur, such as scan completion, scheduled scans, or ticket status changes. This article explains the technical details of how webhooks work, including the structure of webhook payloads and the types of events that trigger notifications.

What are webhook integrations used for?

Webhooks enable integration with various business systems and platforms, including:

Issue tracking systems - Create tickets when vulnerabilities are found
Business intelligence platforms - Aggregate security metrics and trend data
IT service management systems - Route notifications to teams for remediation
Custom applications - Build specialized workflows and automation
Communication platforms - Send alerts to monitoring systems or dashboards

Common data sent through webhooks includes:

Finished scan results and summaries
Scheduled scan notifications (upcoming scans)
Opened and closed tickets with remediation status

How webhooks are delivered

When a triggering event occurs in Holm Security, the system sends an HTTP POST request to your configured webhook endpoint. The request contains a JSON payload with event details.

Webhook delivery flow

Event occurs in Holm Security (scan finishes, ticket opened, scan scheduled)
Security Center prepares a JSON payload with event details
HTTP POST request sent to your webhook endpoint URL
Your system receives and processes the data
Your system can acknowledge receipt or trigger downstream actions

Webhook request structure

Every webhook request contains standard HTTP headers and a JSON body with the event data.

Request headers

All webhook POST requests include these headers:

Content-Type: application/json Content-Length: [size of payload in bytes] User-Agent: python-requests/2.8.1 Host: [your webhook endpoint hostname] Accept: */*

Request payload structure

The JSON payload contains one of three main event types, each with its own data structure:

finished_scan - Notification when a scan completes
scheduled_scan - Notification for upcoming scheduled scans
ticket - Notification when a ticket is opened or closed

Example payload: Finished scan notification

Here's an example of the JSON payload for a completed scan:

{ "finished_scan": { "name": "Daily scan", "type": "network", "status": "Completed", "started": "2024-03-13 12:02", "finished": "2024-03-13 12:59", "duration": "00:57", "critical_cnt": 1, "high_cnt": 3, "medium_cnt": 5, "low_cnt": 12, "errors": "", "link": "https://sc.holmsecurity.com/scans/view/123" } }

Webhook event types and payloads

Scheduled scan notifications

Triggered when a scan is scheduled to run. Contains:

name = Name of the scan as configured in Security Center

type = Type of scan: network or web application

starts_at = Timestamp when the scan will begin (ISO 8601 format)

link = URL to Security Center with scan and schedule settings

Finished scan notifications

Triggered when a scan completes successfully or with errors. Contains:

name = Name of the scan as configured in Security Center

type = Type of scan - network or web application

status = Scan status - should be "Completed" for successful scans

started = Timestamp when scan started (ISO 8601 format)

finished = Timestamp when scan finished (ISO 8601 format)

duration = Total scan duration as a time string (HH:MM:SS format)

errors = Error messages, if any occurred (empty string if no errors, multiple errors separated by double newlines)

critical_cnt = Number of critical vulnerabilities found

high_cnt = Number of high severity vulnerabilities found

medium_cnt = Number of medium severity vulnerabilities found

low_cnt = Number of low severity vulnerabilities found

link = URL to Security Center with detailed scan results

Ticket notifications (open/closed)

Triggered when a ticket is created, updated, or closed. Contains nested data about the asset, ticket, and vulnerability:

Asset Name, Hostname, IPv4, IPv6, OS, Type, Tags, Owner, Business Risk, First Scanned, Last Scanned Ticket Number, Status, Severity, Asset Name, Due Date, Teams Vulnerability Name, Summary, Solution, Impact, Detection, Insight, CVSS2, CVSS3, CVE ID, HID, Exploits, Patches, Ransomware, URL

💡 Tip: Not all fields are present in every notification. Your system should handle missing or null fields gracefully.

Using placeholders in webhooks

Instead of using the fixed JSON structure above, you can customize webhook payloads using placeholders. Placeholders are special variables that get replaced with actual values when the webhook is sent.

For example, instead of receiving the full fixed payload, you can customize your webhook to send only the data you need in a specific format. See the related article for the complete list of available placeholders and how to use them.

Important technical notes

HTTP Method: All webhooks are sent via HTTP POST requests
Content Type: All payloads are JSON formatted (Content-Type: application/json)
Delivery Guarantee: Webhooks are sent immediately when events occur; there is no retry mechanism if delivery fails
Endpoint Availability: Your webhook endpoint must be accessible from Holm Security's infrastructure and respond to POST requests
Payload Size: Payloads vary in size depending on the event type and the amount of vulnerability data included
Timestamps: All timestamps in payloads use ISO 8601 format

Related information

For setup instructions, see:

How do I integrate with Webhooks?

For available placeholders and customization, see:

Which placeholders are available for the Webhooks integration?

For more information, please contact our customer support.