Webhooks (Beta)

Webhooks allow Validin Enterprise Users to receive trigger-based events from the Validin Platform. Any enterprise user can configure webhooks and receive data from across the Validin Platform. Webhooks are currently in beta mode.

🚧

Webhooks are in Beta Mode

The Webhooks UI + Management is subject to change, and support for trigger-based webhooks from additional data sources will be added over time.

Prerequisites

1. A Validin Enterprise Account
2. At least one of the following data sources configured:
   1. YARA Live Hunt
   2. YARA Retro Hunt

Creating your first webhook

Webhooks can be found under the Tools page, located in the sidebar for Validin Enterprise customers.

Steps to create your first webhook:

1. Visit the Webhooks page under Tools
2. Click on the Add a Webhook button on the top right of the page
3. Fill out the following information:
   1. Name (Required)
   2. Description
   3. Webhook URL (Required)
4. Click on Submit to save your new webhook
5. After submitting the webhook, you will receive a signing secret that you must keep secure. You can use the signing secret to verify the authenticity of requests from Validin. More details on how to verify requests can be found below.

🚧

Remember to keep your signing secret secure

Always keep your signing secret secure. You will receive a new, unique signing secret for every webhook you create in the Validin platform. You can always rotate your signing secret in the configuration page for each webhook.

Configuration

On the detailed page for an individual webhook, you can configure Events to give your webhooks access to specific resources.

You can add an Event by clicking the Add button at the top right of the Events table

There are two classes of resources that webhooks can get access to:

1. Projects

   1. You can configure webhooks to alert on observations for YARA rules within a specific project. This will post any observations for all YARA rules in that project.
   2. You can select from the following fields:
   
   

   Field Name	Field Type	Description
   hash	string	Body Hash (as SHA1) of this response
   type	string	body
   source	string	virtual_host or ip4
   mode	string	retro or live
   scheme	string	HTTP or HTTPS
   host	string	Domain used to request host response, if any
   ip	string	IP address of the host response
   start_line	string	First line of the HTTP banner
   title	string	The observed title of the host response
   time	string	Time that we made this scan (in iso8601 format)
   path	string	Path that we visited for this response
   match_time	string	Time that we matched this response via YARA rule (in iso8601 format)
   rule_name	string	YARA rule name
   rule_id	string	YARA rule id
   project_name	string	Project name (that the YARA rule is in)
   port	string	Observed port of host response (integer as a string)
   length	string	"Bytes Received" from the Host Response (integer as a string)

   
   

2. Threats

   1. You can configure alert rules on specific Threat Profiles to post newly observed indicators and references.

   2. You can select from the following fields for indicators and references:

   
   

   Field Name	Field Type	Description
   key	string	Indicators: Domain, IP Address, Path References: URL of the Reference Source
   key_type	string	Indicators: Domain, IP Address, Path References: URL of the Reference Source
   date_added	string	Date we associated this with this threat group in iso8601 format: "2025-01-01T00:00:00Z"
   threat_key	string	The threat key for this particular group: e.g. "lazarus_group". You can fetch detailed information about this group by visiting: VALIDIN_URL/threats/detailed/:threat_key
   display_key	string	The display key of this threat group: e.g. "Lazarus Group"

   
   

Security

Webhooks are sent as POST requests by Validin to the configured URL.

The POST request will include the following headers:

• X-Validin-Request-Timestamp
• X-Validin-Request-Signature

Verifying Request Signature

After configuring your webhook in Validin, you will receive a signing secret that you can use to verify the request.

To verify request authenticity, you can do the following:

1. Verify that the timestamp Validin sends back at X-Validin-Request-Timestamp is less than 5 minutes old to prevent replay attacks
   1. The timestamp is in epoch format (in seconds) as a float to 6 decimal places
2. Verify the HMAC signature passed as a response header: X-Validin-Signature using your signing secret

Here is example python code that demonstrates a way to correctly verify the Validin request signature:

import time
import hmac
import hashlib


def verify_signature(signature: str,
                     timestamp: str,
                     request_body: str,
                     signing_secret: str) -> bool:
    """
    Verifies an HMAC SHA256 signature.

    Args:
        signature: The provided hex-encoded signature string.
        timestamp: The epoch timestamp (string or float in seconds).
        request_body: The raw request body (exact string used when signing).
        signing_secret: Shared secret used to generate HMAC.

    Returns:
        True if valid, False otherwise.
    """

    # 1. Validate timestamp freshness
    try:
        ts = float(timestamp)
    except ValueError:
        return False

    now = time.time()

		# Prevent replay attacks by ensuring that the timestamp is no more than 5 minutes old
    if now - ts > 300:
        return False

    # 2. Reconstruct signed payload
    payload = f"{timestamp}.{request_body}"

    # 3. Compute expected signature
    expected_signature = hmac.new(
        signing_secret.encode("utf-8"),
        payload.encode("utf-8"),
        hashlib.sha256
    ).hexdigest()

    # 4. Validate HMAC Signature
    return hmac.compare_digest(expected_signature, signature)

Whitelisting by IP Address

All requests should come from the following IP Address: 45.63.23.187

📘

Tip

For added security: whitelist your webhook endpoint with the IP Address: 45.63.23.187 and verify the request signature using the signing secret provided.

Testing a Webhook

1. You can test a webhook by clicking on the Test button in the top right of the detailed view. You can customize the event payload and then hit Send to submit the webhook to the configured webhook URL.

Editing a Webhook

1. After creating a webhook, you can select the Edit button to open a popup and edit the webhook configuration. You can edit the following fields: URL, name, and description.

🚧

Editing your webhook URL

Editing your webhook URL will immediately make this change for all future webhook events, excluding any events that are already queued. Only make this change when you are ready to do so and your new webhook URL is configured.

Permissions

1. Webhooks are scoped at the Organization level. Any user in your organization has the ability to create a webhook. If a user in your organization has created a webhook, any other individual can see and edit that Webhook.
2. You can configure webhooks to point to data from any project that you have Edit permissions or higher.
3. You can configure webhooks for any threat profile.