Using Webhooks

Webhooks enable Hydden Discovery to integrate with any HTTP-enabled system by sending automated HTTP requests when events occur. Use webhooks to push data to SIEM platforms, ticketing systems, chat applications, custom APIs, and other external services.

Overview

Webhook providers send HTTP requests to external endpoints when workflow triggers fire. Webhooks are highly flexible and support:

Multiple HTTP methods: GET, POST, PUT
Custom payloads: JSON, XML, or any text format with template variable substitution
Authentication: Bearer tokens and credential-based authentication
Automatic retries: 5 attempts with exponential backoff
Flexible formatting: Send custom payloads or auto-generate from event data

Prerequisites

Before configuring webhook providers:

Target Endpoint: The webhook URL must be accessible from Hydden Discovery
Authentication: If required, create a credential in Configuration > Settings > Credentials or obtain a bearer token
Network Access: Ensure Hydden Discovery can reach the webhook endpoint (check firewalls, network policies)
Endpoint Requirements: Understand the expected payload format, HTTP method, and authentication method for your target system

Add a Webhook Provider

To add a webhook provider:

Navigate to Configuration > Automate.
On the Provider tab, select + Add New.
From the Type drop-down, select Webhook.
For Name, enter a descriptive provider name (e.g., "Splunk SIEM Integration", "Slack Notifications").
For Description, provide an optional description of the provider's purpose.
From the Method drop-down, select the HTTP method:
- POST (default): Most common for webhook integrations
- PUT: For update operations or REST APIs requiring PUT
- GET: For simple notifications or APIs that accept data via query parameters
For URL, provide the complete webhook endpoint URL:
- Must include protocol: https://webhook.example.com/api/events
- Can include query parameters: https://api.example.com/notify?source=hydden
- Must be accessible from Hydden Discovery instance
(Optional) For Token, enter a bearer token if the endpoint requires bearer token authentication:
- Leave blank if using credential-based authentication or no authentication
- Token is sent as Authorization: Bearer <token> header
From the Credential drop-down, select a pre-configured credential if the endpoint requires credential-based authentication:
- Leave blank if using bearer token authentication or no authentication
- Credentials are sent as HTTP Basic Auth or as configured
Click Save.

Authentication Methods

Webhooks support three authentication approaches:

No Authentication

If the webhook endpoint is public or behind a firewall/VPN:

Leave both Token and Credential fields empty
Hydden Discovery will send requests without authentication headers

Bearer Token Authentication

For APIs that require OAuth2 tokens or API keys as bearer tokens:

Enter the token in the Token field on the provider configuration
Leave Credential field empty
Token is sent as: Authorization: Bearer <your-token>

Example:

Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Credential-Based Authentication

For APIs that require username/password or other credential types:

Select a credential from the Credential drop-down
Leave Token field empty
Credentials are sent using HTTP Basic Auth: Authorization: Basic <base64(username:password)>

Example: Create a credential with username api_user and password api_key, then select it in the webhook provider configuration.

Add a Webhook Workflow

To create a webhook workflow:

Navigate to Configuration > Automate.
On the Workflow tab, select + Add New.
For Name, provide a descriptive workflow name (e.g., "Send Threats to Splunk").
For Description, provide an optional workflow purpose description.
From the Trigger drop-down, select the event that should trigger this webhook:
- Threat Detected
- Threat Resolved
- Collection Failed
- Collection Succeeded
- Data Validation Failed
- Data Validation Succeeded
- Classification Added
- Classification Removed
- Entity Alert
From the Action drop-down, select your configured webhook provider.
For Payload, provide the webhook request body:
- Custom payload: Enter JSON, XML, or text with template variables
- Auto-generated payload: Leave empty or enter {} to send full event as JSON
- Template variables: Type { to see available variables (see Triggers)
(Optional) Configure filter options to scope the workflow (see Workflows)
Click Save.
To activate the workflow, toggle the switch in the table row to the on position.

NOTE

A collection must be run successfully at least once before actions can be triggered.

Payload Configuration

Custom Payloads

Custom payloads give you full control over the request body format. Use template variables to include event data.

Example JSON payload (for SIEM integration):

json

{
  "event_type": "threat_detected",
  "timestamp": "{JobTime}",
  "severity": "high",
  "threat": {
    "id": "{ThreatID}",
    "name": "{ThreatName}",
    "score": {Score}
  },
  "affected_accounts": "{Accounts}",
  "platform": "{Platform}",
  "site": "{Site}"
}

Example XML payload:

xml

<alert>
  <type>threat</type>
  <name>{ThreatName}</name>
  <platform>{Platform}</platform>
  <accounts>{Accounts}</accounts>
  <score>{Score}</score>
</alert>

Example plain text payload (for chat applications):

🚨 Threat Alert: {ThreatName}

Platform: {Platform}
Affected Accounts: {Accounts}
Risk Score: {Score}
Site: {Site}

Action Required: Review and remediate immediately.

Auto-Generated Payloads

If you leave the Payload field empty or enter {}, Hydden Discovery automatically sends the complete event object as formatted JSON.

Example auto-generated payload:

json

{
 "title": "Threat Detected",
 "threat_id": "dormant-admin-90",
 "threat_name": "Dormant Admin Account",
 "job_time": "2024-01-15T10:45:00Z",
 "platform": "Active Directory",
 "name": "admin_prod",
 "site": "corp.example.com",
 "status": "detected",
 "score": "85",
 "accounts": "admin_prod, admin_dev",
 "ids": "uuid-1, uuid-2"
}

Auto-generated payloads are useful when:

The target system accepts flexible JSON schemas
You want all event data without filtering
You're prototyping and want to see all available fields

HTTP Methods

POST (Default)

Most webhook integrations use POST to send data to target systems.

Use POST for:

SIEM integrations (Splunk, LogRhythm, QRadar)
Ticketing systems (Jira, ServiceNow alternatives)
Chat applications (Slack, Teams, Discord)
Custom APIs that create resources

Characteristics:

Request body contains payload
Content-Type: application/json header set automatically
Most common webhook method

PUT

Use PUT for REST APIs that require update semantics or idempotent operations.

Use PUT for:

REST APIs with update operations
Systems that require idempotent requests
APIs that use resource-based URL patterns

Characteristics:

Request body contains payload
Content-Type: application/json header set automatically
Less common than POST

GET

Use GET for simple notifications or systems that accept data via query parameters.

Use GET for:

Simple notification endpoints
Health check pings
Legacy systems expecting query parameters

Characteristics:

No request body
Data must be in URL or query parameters
Less common for webhook integrations

Retry and Error Handling

Webhooks include automatic retry logic to handle transient failures:

Retry Configuration

Retry Attempts: 5 automatic retries
Timeout: 10 seconds per request
Success Criteria: HTTP 200 status code
Failure: Any non-200 status code or timeout

Retry Behavior

Initial Request: Webhook sends initial HTTP request
Failure Detection: If status code is not 200 or timeout occurs, request is marked as failed
Exponential Backoff: Subsequent retries wait progressively longer (exponential backoff)
Final Failure: After 5 failed attempts, the workflow is marked as failed and logged

Error Logging

All webhook failures are logged with:

Workflow ID and name
Action provider ID and name
HTTP status code (if received)
Error message
Timestamp

Check Hydden Discovery logs for webhook troubleshooting information.

Common Integration Examples

Splunk SIEM Integration

Provider Configuration:

Type: Webhook
Method: POST
URL: https://splunk.example.com:8088/services/collector/event
Token: Your Splunk HEC token

Workflow Payload:

json

{
  "sourcetype": "hydden:threat",
  "event": {
    "threat_name": "{ThreatName}",
    "threat_id": "{ThreatID}",
    "platform": "{Platform}",
    "accounts": "{Accounts}",
    "score": {Score},
    "site": "{Site}",
    "timestamp": "{JobTime}"
  }
}

Slack Notifications

Provider Configuration:

Type: Webhook
Method: POST
URL: Your Slack incoming webhook URL

Workflow Payload:

json

{
  "text": "🚨 Threat Detected: {ThreatName}",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*Threat Details*\n*Name:* {ThreatName}\n*Platform:* {Platform}\n*Accounts:* {Accounts}\n*Score:* {Score}"
      }
    }
  ]
}

Microsoft Teams Notifications

Provider Configuration:

Type: Webhook
Method: POST
URL: Your Teams incoming webhook URL

Workflow Payload:

json

{
  "@type": "MessageCard",
  "@context": "https://schema.org/extensions",
  "summary": "Threat Detected",
  "themeColor": "FF0000",
  "title": "🚨 Threat Detected: {ThreatName}",
  "sections": [
    {
      "activityTitle": "Threat Details",
      "facts": [
        {
          "name": "Platform:",
          "value": "{Platform}"
        },
        {
          "name": "Accounts:",
          "value": "{Accounts}"
        },
        {
          "name": "Risk Score:",
          "value": "{Score}"
        },
        {
          "name": "Site:",
          "value": "{Site}"
        }
      ]
    }
  ]
}

Jira Issue Creation

Provider Configuration:

Type: Webhook
Method: POST
URL: https://your-instance.atlassian.net/rest/api/2/issue
Credential: Jira API credential (email + API token)

Workflow Payload:

json

{
  "fields": {
    "project": {
      "key": "SEC"
    },
    "summary": "Threat Detected: {ThreatName} on {Platform}",
    "description": "Threat {ThreatName} was detected on {Platform} affecting accounts: {Accounts}. Risk Score: {Score}. Site: {Site}.",
    "issuetype": {
      "name": "Bug"
    },
    "priority": {
      "name": "High"
    }
  }
}

Custom REST API

Provider Configuration:

Type: Webhook
Method: POST or PUT
URL: Your API endpoint
Token or Credential: Based on your API requirements

Workflow Payload: Design based on your API's schema requirements

Troubleshooting

Issue	Solution
Webhook not firing	Verify workflow is enabled, check trigger matches event type, ensure webhook provider is configured
HTTP timeout errors	Check network connectivity to webhook endpoint, verify endpoint responds within 10 seconds, check firewall rules
Authentication failures	Verify bearer token or credentials are correct, check if token has expired, confirm endpoint authentication requirements
400 Bad Request	Verify payload format matches endpoint expectations, check required fields are present, validate JSON syntax
401 Unauthorized	Check authentication credentials, verify bearer token is valid, confirm endpoint auth method matches provider config
403 Forbidden	Verify API credentials have required permissions, check IP allowlists on target system
404 Not Found	Verify webhook URL is correct, check for typos in URL, confirm endpoint path exists
500 Internal Server Error	Check webhook endpoint logs for errors, verify payload data is valid, contact endpoint administrator
SSL/TLS errors	Ensure webhook URL uses `https://`, verify SSL certificate is valid, check certificate chain
Variables not substituting	Verify variable names match trigger type (see Triggers), check syntax uses `{Variable}` format
Payload too large	Reduce payload size, use filter options to limit event scope, contact endpoint administrator about size limits
Retries exhausted	Check webhook endpoint availability, verify endpoint can handle request volume, review error logs for root cause

Best Practices

Security

Use HTTPS: Always use https:// URLs for webhooks to encrypt data in transit
Rotate Tokens: Periodically rotate bearer tokens and credentials
Least Privilege: Grant webhook endpoints minimal required permissions
Validate Endpoints: Test webhook endpoints before enabling production workflows
Monitor Failures: Regularly review webhook failure logs

Payload Design

Include Context: Include relevant event details in payloads to provide context
Keep it Simple: Don't include unnecessary fields that increase payload size
Test Payloads: Test payload formats with target systems before production use
Use Variables: Leverage template variables to dynamically populate data
Format Appropriately: Match payload format to endpoint expectations (JSON, XML, etc.)

Performance

Filter Workflows: Use workflow filters to reduce unnecessary webhook calls
Batch When Possible: If target system supports batching, consider aggregating events
Monitor Volume: Track webhook call volume to avoid overwhelming target systems
Rate Limit Awareness: Be aware of rate limits on target systems

Operational

Descriptive Names: Use clear provider and workflow names that indicate purpose
Document Integrations: Document webhook configurations and purposes
Test Thoroughly: Test webhooks with sample events before production use
Monitor Success Rate: Track webhook success rates and investigate failures

Overview - Automation architecture and concepts
Workflows - Creating and managing workflows
Triggers - Available trigger types and variables
Providers - Configuring email providers
ServiceNow Ticket Actions - ServiceNow integration
Add to Vault - PAM integration for auto-vaulting
Credentials - Managing credentials for providers

Data Sources

Universal Collector Overview

Threat Detection Rules

OpenID Providers

Credentials

How to use the CyberArk Integration

Using Webhooks ​

Overview ​

Prerequisites ​

Add a Webhook Provider ​

Authentication Methods ​

No Authentication ​

Bearer Token Authentication ​

Credential-Based Authentication ​

Add a Webhook Workflow ​

Payload Configuration ​

Custom Payloads ​

Auto-Generated Payloads ​

HTTP Methods ​

POST (Default) ​

PUT ​

GET ​

Retry and Error Handling ​

Retry Configuration ​

Retry Behavior ​

Error Logging ​

Common Integration Examples ​

Splunk SIEM Integration ​

Slack Notifications ​

Microsoft Teams Notifications ​

Jira Issue Creation ​

Custom REST API ​

Troubleshooting ​

Best Practices ​

Security ​

Payload Design ​

Performance ​

Operational ​

Related Topics ​

Using Webhooks

Overview

Prerequisites

Add a Webhook Provider

Authentication Methods

No Authentication

Bearer Token Authentication

Credential-Based Authentication

Add a Webhook Workflow

Payload Configuration

Custom Payloads

Auto-Generated Payloads

HTTP Methods

POST (Default)

PUT

GET

Retry and Error Handling

Retry Configuration

Retry Behavior

Error Logging

Common Integration Examples

Splunk SIEM Integration

Slack Notifications

Microsoft Teams Notifications

Jira Issue Creation

Custom REST API

Troubleshooting

Best Practices

Security

Payload Design

Performance

Operational

Related Topics