EDR/XDR Webhooks

Webhook Configuration

To set up webhooks for your integration, visit the Unizo Console Webhooks section for step-by-step configuration guide.

Overview

Unizo's EDR/XDR API provides webhooks to notify your application when critical security events occur across your endpoint detection and response platforms. These real-time notifications enable you to build automated security response workflows, maintain compliance, and quickly react to threats.

Our platform normalizes webhook events from various EDR/XDR providers (CrowdStrike, SentinelOne, Microsoft Defender, etc.) into a consistent format, simplifying security event handling across multiple platforms.

Supported Event Types

Event Type	Description	Trigger Conditions
	Triggered when a new threat is detected on an endpoint
	Triggered when a threat is successfully remediated
	Triggered when a file or process is quarantined
	Triggered when an endpoint is isolated from the network
	Triggered when an endpoint is restored to the network
	Triggered when an endpoint goes offline
	Triggered when a security policy is violated
	Triggered when a security scan completes
	Triggered for critical security alerts requiring immediate attention

Webhook Security

All webhooks from Unizo include security headers to verify authenticity:

Headers

Header	Description
`x-unizo-event-type`	The type of event that triggered the webhook
`x-unizo-signature`	HMAC SHA-256 signature for request validation
`x-unizo-timestamp`	Unix timestamp when the event was sent
`x-unizo-delivery-id`	Unique identifier for this webhook delivery

Signature Verification

Verify the authenticity of incoming webhooks using HMAC SHA-256:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

Event Details

Threat Events

Threat Detected

`threat:detected`

Triggered when a new threat, malware, or suspicious activity is detected on an endpoint by the EDR/XDR platform.

POSThttps://api.yourapp.com/webhooks/unizo/scm

Best Practice: Use a dedicated webhook endpoint that can handle multiple event types. You have two architectural options:
• Single endpoint: https://api.yourapp.com/webhooks/unizo - Route all events to one handler
• Category-based endpoints: https://api.yourapp.com/webhooks/unizo/scm - Route by category (scm, ticketing, etc.) for microservices architecture

Headers

Name	Type	Required	Description
`Content-Type`	string	Yes	Always application/json
`x-unizo-event-type`	string	Yes	Event type: threat:detected
`x-unizo-webhook-id`	string	Yes	Unique webhook configuration ID
`x-unizo-delivery-id`	string	Yes	Unique delivery attempt ID
`x-unizo-signature`	string	Yes	HMAC SHA256 signature for verification

Request Body Schema

Property	Type	Required	Description
`type`	string	Yes	Event type identifier
`version`	string	Yes	Webhook payload version
`data.threat.id`	string	Yes	Unique threat identifier
`data.threat.name`	string	Yes	Threat name or signature
`data.threat.type`	string	Yes	Threat classification (malware, ransomware, trojan, pup, suspicious_activity)
`data.threat.severity`	string	Yes	Threat severity level (critical, high, medium, low)
`data.threat.file_path`	string	No	Full path of the affected file
`data.threat.file_hash`	string	No	SHA256 hash of the file
`data.threat.process_name`	string	No	Name of the affected process
`data.threat.detected_at`	string	Yes	Detection timestamp (ISO 8601)
`data.endpoint.id`	string	Yes	Endpoint identifier
`data.endpoint.hostname`	string	Yes	Endpoint hostname
`data.endpoint.ip_address`	string	No	Endpoint IP address
`data.endpoint.os`	string	Yes	Operating system
`data.endpoint.user`	string	No	Logged-in user
`data.detection_method`	string	No	How the threat was detected
`data.recommended_action`	string	No	Recommended remediation action
`integration.id`	string	Yes	Integration ID
`integration.name`	string	Yes	Integration name
`integration.provider`	string	Yes	EDR provider name

Example Payload

{
  "type": "threat:detected",
  "version": "1.0.0",
  "data": {
    "threat": {
      "id": "thr_abc123def456",
      "name": "Trojan:Win32/Emotet",
      "type": "trojan",
      "severity": "critical",
      "file_path": "C:\\Users\\john.doe\\Downloads\\invoice.exe",
      "file_hash": "a123b456c789d012e345f678g901h234",
      "process_name": "invoice.exe",
      "detected_at": "2024-06-15T14:30:00Z"
    },
    "endpoint": {
      "id": "ep_workstation_123",
      "hostname": "DESKTOP-ABC123",
      "ip_address": "192.168.1.100",
      "os": "Windows 10 Pro",
      "user": "CORP\\john.doe"
    },
    "detection_method": "Behavioral Analysis",
    "recommended_action": "Quarantine and remove file"
  },
  "integration": {
    "id": "int_crowdstrike_789",
    "name": "Company CrowdStrike",
    "provider": "crowdstrike"
  }
}

Response

`200 OK`	Webhook processed successfully
`400 Bad Request`	Invalid webhook payload
`401 Unauthorized`	Invalid or missing signature

Threat Remediated

`threat:remediated`

Triggered when a detected threat has been successfully remediated or removed from an endpoint.

POSThttps://api.yourapp.com/webhooks/unizo/scm

Headers

Name	Type	Required	Description
`Content-Type`	string	Yes	Always application/json
`x-unizo-event-type`	string	Yes	Event type: threat:remediated
`x-unizo-webhook-id`	string	Yes	Unique webhook configuration ID
`x-unizo-delivery-id`	string	Yes	Unique delivery attempt ID
`x-unizo-signature`	string	Yes	HMAC SHA256 signature for verification

Request Body Schema

Property	Type	Required	Description
`type`	string	Yes	Event type identifier
`version`	string	Yes	Webhook payload version
`data.threat_id`	string	Yes	Original threat identifier
`data.threat_name`	string	Yes	Threat name
`data.remediation.action`	string	Yes	Action taken (removed, quarantined, restored, blocked)
`data.remediation.status`	string	Yes	Remediation status (success, partial, failed)
`data.remediation.completed_at`	string	Yes	Completion timestamp (ISO 8601)
`data.remediation.performed_by`	string	Yes	Who initiated the remediation
`data.endpoint.id`	string	Yes	Endpoint identifier
`data.endpoint.hostname`	string	Yes	Endpoint hostname
`integration.id`	string	Yes	Integration ID
`integration.name`	string	Yes	Integration name
`integration.provider`	string	Yes	EDR provider name

Example Payload

{
  "type": "threat:remediated",
  "version": "1.0.0",
  "data": {
    "threat_id": "thr_abc123def456",
    "threat_name": "Trojan:Win32/Emotet",
    "remediation": {
      "action": "removed",
      "status": "success",
      "completed_at": "2024-06-15T14:35:00Z",
      "performed_by": "Automated Response"
    },
    "endpoint": {
      "id": "ep_workstation_123",
      "hostname": "DESKTOP-ABC123"
    }
  },
  "integration": {
    "id": "int_crowdstrike_789",
    "name": "Company CrowdStrike",
    "provider": "crowdstrike"
  }
}

Response

`200 OK`	Webhook processed successfully
`400 Bad Request`	Invalid webhook payload
`401 Unauthorized`	Invalid or missing signature

Endpoint Events

Endpoint Isolated

`endpoint:isolated`

Triggered when an endpoint is isolated from the network as a containment measure.

POSThttps://api.yourapp.com/webhooks/unizo/scm

Headers

Name	Type	Required	Description
`Content-Type`	string	Yes	Always application/json
`x-unizo-event-type`	string	Yes	Event type: endpoint:isolated
`x-unizo-webhook-id`	string	Yes	Unique webhook configuration ID
`x-unizo-delivery-id`	string	Yes	Unique delivery attempt ID
`x-unizo-signature`	string	Yes	HMAC SHA256 signature for verification

Request Body Schema

Property	Type	Required	Description
`type`	string	Yes	Event type identifier
`version`	string	Yes	Webhook payload version
`data.endpoint.id`	string	Yes	Endpoint identifier
`data.endpoint.hostname`	string	Yes	Endpoint hostname
`data.endpoint.ip_address`	string	No	Last known IP address
`data.endpoint.os`	string	Yes	Operating system
`data.endpoint.last_user`	string	No	Last logged-in user
`data.isolation.reason`	string	Yes	Reason for isolation
`data.isolation.initiated_by`	string	Yes	Who initiated isolation
`data.isolation.isolated_at`	string	Yes	Isolation timestamp (ISO 8601)
`data.isolation.expected_duration`	string	No	Expected isolation duration
`data.related_threat_id`	string	No	Related threat ID if applicable
`integration.id`	string	Yes	Integration ID
`integration.name`	string	Yes	Integration name
`integration.provider`	string	Yes	EDR provider name

Example Payload

{
  "type": "endpoint:isolated",
  "version": "1.0.0",
  "data": {
    "endpoint": {
      "id": "ep_workstation_123",
      "hostname": "DESKTOP-ABC123",
      "ip_address": "192.168.1.100",
      "os": "Windows 10 Pro",
      "last_user": "CORP\\john.doe"
    },
    "isolation": {
      "reason": "Critical malware detected - Emotet trojan",
      "initiated_by": "Automated Response Policy",
      "isolated_at": "2024-06-15T14:31:00Z",
      "expected_duration": "Until manual review"
    },
    "related_threat_id": "thr_abc123def456"
  },
  "integration": {
    "id": "int_sentinelone_456",
    "name": "Company SentinelOne",
    "provider": "sentinelone"
  }
}

Response

`200 OK`	Webhook processed successfully
`400 Bad Request`	Invalid webhook payload
`401 Unauthorized`	Invalid or missing signature

Alert Events

Critical Alert

`alert:critical`

Triggered when a critical security alert is generated that requires immediate attention.

POSThttps://api.yourapp.com/webhooks/unizo/scm

Headers

Name	Type	Required	Description
`Content-Type`	string	Yes	Always application/json
`x-unizo-event-type`	string	Yes	Event type: alert:critical
`x-unizo-webhook-id`	string	Yes	Unique webhook configuration ID
`x-unizo-delivery-id`	string	Yes	Unique delivery attempt ID
`x-unizo-signature`	string	Yes	HMAC SHA256 signature for verification

Request Body Schema

Property	Type	Required	Description
`type`	string	Yes	Event type identifier
`version`	string	Yes	Webhook payload version
`data.alert.id`	string	Yes	Alert identifier
`data.alert.title`	string	Yes	Alert title
`data.alert.description`	string	Yes	Detailed alert description
`data.alert.severity`	string	Yes	Alert severity (critical)
`data.alert.category`	string	Yes	Alert category
`data.alert.created_at`	string	Yes	Alert creation time (ISO 8601)
`data.affected_endpoints`	array	Yes	List of affected endpoints
`data.indicators`	array	No	Threat indicators
`data.recommended_actions`	array	No	Recommended response actions
`integration.id`	string	Yes	Integration ID
`integration.name`	string	Yes	Integration name
`integration.provider`	string	Yes	EDR provider name

Example Payload

{
  "type": "alert:critical",
  "version": "1.0.0",
  "data": {
    "alert": {
      "id": "alrt_789xyz",
      "title": "Ransomware Activity Detected",
      "description": "Multiple endpoints showing signs of ransomware encryption activity",
      "severity": "critical",
      "category": "Ransomware",
      "created_at": "2024-06-15T14:45:00Z"
    },
    "affected_endpoints": [
      {
        "id": "ep_workstation_123",
        "hostname": "DESKTOP-ABC123"
      },
      {
        "id": "ep_workstation_456",
        "hostname": "DESKTOP-XYZ789"
      }
    ],
    "indicators": [
      "Mass file encryption detected",
      "Known ransomware file extensions created",
      "Volume shadow copy deletion attempts"
    ],
    "recommended_actions": [
      "Isolate affected endpoints immediately",
      "Initiate incident response protocol",
      "Check backups availability",
      "Contact security team"
    ]
  },
  "integration": {
    "id": "int_defender_123",
    "name": "Microsoft Defender",
    "provider": "microsoft_defender"
  }
}

Response

`200 OK`	Webhook processed successfully
`400 Bad Request`	Invalid webhook payload
`401 Unauthorized`	Invalid or missing signature

Webhook Delivery & Retries

Unizo implements a robust delivery system with automatic retries to ensure your webhooks are delivered reliably:

Timeout: 30 seconds per delivery attempt
Retry Schedule: 5 attempts with exponential backoff
- Attempt 1: Immediate
- Attempt 2: 1 minute delay
- Attempt 3: 5 minutes delay
- Attempt 4: 30 minutes delay
- Attempt 5: 2 hours delay
Success Criteria: HTTP status codes 200-299
Failure Handling: After 5 failed attempts, the webhook is marked as failed

Best Practices

1. Idempotency

Always implement idempotent webhook handlers using the x-unizo-delivery-id header:

Idempotent Webhook Handler

// Example: Handling webhooks idempotently
app.post('/webhooks/edr', async (req, res) => {
const deliveryId = req.headers['x-unizo-delivery-id'];

// Check if we've already processed this delivery
const existingDelivery = await db.webhookDeliveries.findOne({ 
  deliveryId 
});

if (existingDelivery) {
  console.log(`Duplicate delivery detected: ${deliveryId}`);
  return res.status(200).json({ 
    status: 'already_processed' 
  });
}

// Process the webhook
try {
  await processSecurityEvent(req.body);
  
  // Record the delivery
  await db.webhookDeliveries.create({
    deliveryId,
    processedAt: new Date()
  });
  
  res.status(200).json({ status: 'success' });
} catch (error) {
  console.error('Webhook processing failed:', error);
  res.status(500).json({ status: 'error' });
}
});

2. Security Response Automation

Implement automated security responses for critical events:

Automated Security Response

// Example: Automated threat response
app.post('/webhooks/edr', async (req, res) => {
const { type, data } = req.body;

// Acknowledge receipt immediately
res.status(200).json({ status: 'received' });

switch (type) {
  case 'threat:detected':
    if (data.threat.severity === 'critical') {
      // Auto-isolate for critical threats
      await edrApi.isolateEndpoint(data.endpoint.id);
      
      // Create incident ticket
      await ticketingApi.createIncident({
        title: `Critical threat: ${data.threat.name}`,
        priority: 'P1',
        endpoint: data.endpoint.hostname,
        assignTo: 'security-team'
      });
      
      // Send alerts
      await alertingService.sendCriticalAlert({
        channel: 'security-incidents',
        message: `Critical threat detected on ${data.endpoint.hostname}`
      });
    }
    break;
    
  case 'alert:critical':
    // Trigger incident response workflow
    await incidentResponse.initiate({
      alertId: data.alert.id,
      affectedEndpoints: data.affected_endpoints,
      playbook: 'critical-security-incident'
    });
    break;
}
});

3. Compliance and Audit Logging

Maintain comprehensive audit logs for compliance:

Compliance Logging

// Example: Compliance and audit logging
app.post('/webhooks/edr', async (req, res) => {
const { type, data, integration } = req.body;

// Create audit log entry
const auditEntry = {
  eventType: type,
  timestamp: new Date(),
  source: {
    integration: integration.name,
    provider: integration.provider
  },
  details: {
    // Extract key fields for audit
    threatId: data.threat?.id,
    endpointId: data.endpoint?.id,
    severity: data.threat?.severity || data.alert?.severity,
    action: data.remediation?.action
  },
  rawEvent: req.body // Store full event for compliance
};

// Store in compliance database
await complianceDb.securityEvents.create(auditEntry);

// Forward to SIEM if configured
if (config.siem.enabled) {
  await siemConnector.sendEvent({
    source: 'unizo-edr-webhook',
    event: auditEntry
  });
}

res.status(200).json({ status: 'logged' });
});

Need Help?

For webhook-related support:

Contact support at support@unizo.ai

Overview​

Supported Event Types​

Webhook Security

Headers

Signature Verification

Event Details​

Threat Events​

Threat Detected

threat:detected

Headers

Request Body Schema

Example Payload

Response

Threat Remediated

threat:remediated

Headers

Request Body Schema

Example Payload

Response

Endpoint Events​

Endpoint Isolated

endpoint:isolated

Headers

Request Body Schema

Example Payload

Response

Alert Events​

Critical Alert

alert:critical

Headers

Request Body Schema

Example Payload

Response

Webhook Delivery & Retries​

Best Practices​

1. Idempotency​

Idempotent Webhook Handler

2. Security Response Automation​

Automated Security Response

3. Compliance and Audit Logging​

Compliance Logging

Need Help?​

Overview

Supported Event Types

Event Details

Threat Events

`threat:detected`

`threat:remediated`

Endpoint Events

`endpoint:isolated`

Alert Events

`alert:critical`

Webhook Delivery & Retries

Best Practices

1. Idempotency

2. Security Response Automation

3. Compliance and Audit Logging

Need Help?