Observability Webhooks

Webhooks enable your applications to receive real-time notifications when events occur in your monitoring and observability systems. This eliminates the need for polling and ensures your systems stay synchronized with alerts, metrics, and infrastructure changes across all integrated platforms.

Unizo normalizes webhook events from Datadog, New Relic, Splunk, Prometheus, Grafana, and other observability providers into a consistent format. This means you write your webhook handler once and it works with all supported platforms.

Webhook Configuration

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

Supported Event Types

These are the event types currently supported by Unizo's Observability webhooks. The list keeps growing as we add support for more events across different platforms.

Event Type	Description	Trigger Conditions
alert:triggered	An alert has been triggered	Threshold breach, anomaly detection, or custom conditions
alert:resolved	An alert has been resolved	Metrics return to normal or manual resolution
alert:acknowledged	An alert has been acknowledged	User acknowledges the alert
monitor:created	A new monitor has been created	Monitor creation via UI or API
monitor:updated	Monitor configuration has been modified	Threshold, condition, or notification changes
monitor:deleted	A monitor has been deleted	Monitor removal from the system
dashboard:created	A new dashboard has been created	Dashboard creation via UI or API
dashboard:updated	Dashboard has been modified	Widget additions, layout changes, or filter updates
metric:anomaly_detected	Anomaly detected in metrics	ML-based anomaly detection or statistical deviation

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

Alert Events

Event Type	Description	Trigger Conditions
alert:triggered	An alert has been triggered	Threshold breach, anomaly detection, or custom conditions
alert:resolved	An alert has been resolved	Metrics return to normal or manual resolution
alert:acknowledged	An alert has been acknowledged	User acknowledges the alert

Alert Triggered

`alert:triggered`

Triggered when an alert condition is met in the monitoring system

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

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/observability - Route by category (observability, 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: alert:triggered
`x-unizo-webhook-id`	string	Yes	Unique webhook configuration ID
`x-unizo-delivery-id`	string	Yes	Unique delivery ID for idempotency
`x-unizo-signature`	string	Yes	HMAC SHA-256 signature

Request Body Schema

Property	Type	Required	Description
`type`	string	Yes	Event type identifier
`version`	string	Yes	Webhook payload version
`alert.id`	string	Yes	Unique alert identifier
`alert.name`	string	Yes	Alert name
`alert.description`	string	No	Alert description
`alert.severity`	string	Yes	Severity level: critical, high, medium, low
`alert.status`	string	Yes	Current status: triggered, acknowledged, resolved
`alert.metric`	object	Yes	Metric that triggered the alert
`alert.threshold`	object	Yes	Threshold configuration
`alert.triggeredDateTime`	string	Yes	ISO 8601 timestamp
`alert.tags`	array	No	Associated tags
`integration`	object	Yes	Integration details

Example Payload

{
  "type": "alert:triggered",
  "version": "1.0.0",
  "alert": {
    "id": "alert-123456",
    "name": "High CPU Usage - Production Server",
    "description": "CPU usage exceeded 90% for more than 5 minutes",
    "severity": "critical",
    "status": "triggered",
    "metric": {
      "name": "system.cpu.usage",
      "value": 92.5,
      "unit": "percentage",
      "host": "prod-web-01"
    },
    "threshold": {
      "operator": "greater_than",
      "value": 90,
      "duration": "5m"
    },
    "triggeredDateTime": "2024-01-15T14:00:00Z",
    "tags": [
      "production",
      "web-server",
      "critical"
    ]
  },
  "integration": {
    "type": "OBSERVABILITY",
    "id": "int_123456",
    "name": "Datadog Production",
    "provider": "datadog"
  }
}

Response

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

Alert Resolved

`alert:resolved`

Triggered when an alert condition is no longer met

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: alert:resolved
`x-unizo-webhook-id`	string	Yes	Unique webhook configuration ID
`x-unizo-delivery-id`	string	Yes	Unique delivery ID for idempotency
`x-unizo-signature`	string	Yes	HMAC SHA-256 signature

Request Body Schema

Property	Type	Required	Description
`type`	string	Yes	Event type identifier
`version`	string	Yes	Webhook payload version
`alert.id`	string	Yes	Unique alert identifier
`alert.name`	string	Yes	Alert name
`alert.severity`	string	Yes	Severity level
`alert.status`	string	Yes	Current status: resolved
`alert.duration`	string	Yes	How long the alert was active
`alert.resolvedDateTime`	string	Yes	ISO 8601 timestamp
`alert.resolvedBy`	string	Yes	Resolution method: auto, manual
`integration`	object	Yes	Integration details

Example Payload

{
  "type": "alert:resolved",
  "version": "1.0.0",
  "alert": {
    "id": "alert-123456",
    "name": "High CPU Usage - Production Server",
    "severity": "critical",
    "status": "resolved",
    "duration": "15m30s",
    "resolvedDateTime": "2024-01-15T14:15:30Z",
    "resolvedBy": "auto",
    "metric": {
      "name": "system.cpu.usage",
      "value": 75.2,
      "unit": "percentage",
      "host": "prod-web-01"
    }
  },
  "integration": {
    "type": "OBSERVABILITY",
    "id": "int_123456",
    "name": "Datadog Production",
    "provider": "datadog"
  }
}

Response

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

Alert Acknowledged

`alert:acknowledged`

Triggered when a user acknowledges an alert

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: alert:acknowledged
`x-unizo-webhook-id`	string	Yes	Unique webhook configuration ID
`x-unizo-delivery-id`	string	Yes	Unique delivery ID for idempotency
`x-unizo-signature`	string	Yes	HMAC SHA-256 signature

Request Body Schema

Property	Type	Required	Description
`type`	string	Yes	Event type identifier
`version`	string	Yes	Webhook payload version
`alert.id`	string	Yes	Unique alert identifier
`alert.name`	string	Yes	Alert name
`alert.status`	string	Yes	Current status: acknowledged
`acknowledgment.note`	string	No	Acknowledgment note
`acknowledgment.acknowledgedBy`	object	Yes	User who acknowledged
`acknowledgment.acknowledgedDateTime`	string	Yes	ISO 8601 timestamp
`integration`	object	Yes	Integration details

Example Payload

{
  "type": "alert:acknowledged",
  "version": "1.0.0",
  "alert": {
    "id": "alert-123456",
    "name": "High CPU Usage - Production Server",
    "status": "acknowledged"
  },
  "acknowledgment": {
    "note": "Investigating the issue, likely due to traffic spike",
    "acknowledgedBy": {
      "id": "user-789",
      "email": "ops@example.com",
      "name": "John Ops"
    },
    "acknowledgedDateTime": "2024-01-15T14:05:00Z"
  },
  "integration": {
    "type": "OBSERVABILITY",
    "id": "int_123456",
    "name": "PagerDuty",
    "provider": "pagerduty"
  }
}

Response

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

Monitor Events

Event Type	Description	Trigger Conditions
monitor:created	A new monitor has been created	Monitor creation via UI or API
monitor:updated	Monitor configuration has been modified	Threshold, condition, or notification changes
monitor:deleted	A monitor has been deleted	Monitor removal from the system

Monitor Created

`monitor:created`

Triggered when a new monitor is created in the observability system

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: monitor:created
`x-unizo-webhook-id`	string	Yes	Unique webhook configuration ID
`x-unizo-delivery-id`	string	Yes	Unique delivery ID for idempotency
`x-unizo-signature`	string	Yes	HMAC SHA-256 signature

Request Body Schema

Property	Type	Required	Description
`type`	string	Yes	Event type identifier
`version`	string	Yes	Webhook payload version
`monitor.id`	string	Yes	Unique monitor identifier
`monitor.name`	string	Yes	Monitor name
`monitor.type`	string	Yes	Monitor type: metric, log, synthetic
`monitor.query`	string	Yes	Monitor query or condition
`monitor.thresholds`	object	Yes	Alert thresholds
`monitor.createdDateTime`	string	Yes	ISO 8601 timestamp
`monitor.createdBy`	object	Yes	User who created the monitor
`integration`	object	Yes	Integration details

Example Payload

{
  "type": "monitor:created",
  "version": "1.0.0",
  "monitor": {
    "id": "monitor-456",
    "name": "API Response Time Monitor",
    "type": "metric",
    "query": "avg(last_5m):avg:api.response_time{service:payment} > 1000",
    "thresholds": {
      "critical": 1000,
      "warning": 500
    },
    "createdDateTime": "2024-01-15T14:00:00Z",
    "createdBy": {
      "id": "user-123",
      "email": "devops@example.com",
      "name": "DevOps Team"
    }
  },
  "integration": {
    "type": "OBSERVABILITY",
    "id": "int_123456",
    "name": "New Relic Production",
    "provider": "newrelic"
  }
}

Response

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

Dashboard Events

Event Type	Description	Trigger Conditions
dashboard:created	A new dashboard has been created	Dashboard creation via UI or API
dashboard:updated	Dashboard has been modified	Widget additions, layout changes, or filter updates

Dashboard Created

`dashboard:created`

Triggered when a new dashboard is created

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: dashboard:created
`x-unizo-webhook-id`	string	Yes	Unique webhook configuration ID
`x-unizo-delivery-id`	string	Yes	Unique delivery ID for idempotency
`x-unizo-signature`	string	Yes	HMAC SHA-256 signature

Request Body Schema

Property	Type	Required	Description
`type`	string	Yes	Event type identifier
`version`	string	Yes	Webhook payload version
`dashboard.id`	string	Yes	Unique dashboard identifier
`dashboard.name`	string	Yes	Dashboard name
`dashboard.description`	string	No	Dashboard description
`dashboard.widgets`	array	Yes	List of widgets
`dashboard.createdDateTime`	string	Yes	ISO 8601 timestamp
`dashboard.createdBy`	object	Yes	User who created the dashboard
`integration`	object	Yes	Integration details

Example Payload

{
  "type": "dashboard:created",
  "version": "1.0.0",
  "dashboard": {
    "id": "dashboard-789",
    "name": "Production Overview",
    "description": "Main production environment metrics",
    "widgets": [
      {
        "id": "widget-1",
        "type": "timeseries",
        "title": "CPU Usage"
      },
      {
        "id": "widget-2",
        "type": "heatmap",
        "title": "Request Distribution"
      }
    ],
    "createdDateTime": "2024-01-15T14:00:00Z",
    "createdBy": {
      "id": "user-456",
      "email": "admin@example.com",
      "name": "Admin User"
    }
  },
  "integration": {
    "type": "OBSERVABILITY",
    "id": "int_123456",
    "name": "Grafana Cloud",
    "provider": "grafana"
  }
}

Response

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

Anomaly Events

Event Type	Description	Trigger Conditions
metric:anomaly_detected	Anomaly detected in metrics	ML-based anomaly detection or statistical deviation

Anomaly Detected

`metric:anomaly_detected`

Triggered when an anomaly is detected in metrics

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: metric:anomaly_detected
`x-unizo-webhook-id`	string	Yes	Unique webhook configuration ID
`x-unizo-delivery-id`	string	Yes	Unique delivery ID for idempotency
`x-unizo-signature`	string	Yes	HMAC SHA-256 signature

Request Body Schema

Property	Type	Required	Description
`type`	string	Yes	Event type identifier
`version`	string	Yes	Webhook payload version
`anomaly.id`	string	Yes	Unique anomaly identifier
`anomaly.metric`	string	Yes	Metric name
`anomaly.deviation`	number	Yes	Deviation from normal
`anomaly.confidence`	number	Yes	Confidence score (0-1)
`anomaly.detectedDateTime`	string	Yes	ISO 8601 timestamp
`anomaly.context`	object	Yes	Additional context
`integration`	object	Yes	Integration details

Example Payload

{
  "type": "metric:anomaly_detected",
  "version": "1.0.0",
  "anomaly": {
    "id": "anomaly-123",
    "metric": "api.request_count",
    "deviation": 3.5,
    "confidence": 0.95,
    "detectedDateTime": "2024-01-15T14:00:00Z",
    "context": {
      "expected": 1000,
      "actual": 3500,
      "service": "payment-api",
      "environment": "production"
    }
  },
  "integration": {
    "type": "OBSERVABILITY",
    "id": "int_123456",
    "name": "Splunk Enterprise",
    "provider": "splunk"
  }
}

Response

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

Webhook Delivery & Retries

Unizo implements automatic retry logic for failed webhook deliveries:

Initial Delivery: Immediate
First Retry: After 1 minute
Second Retry: After 5 minutes
Third Retry: After 15 minutes
Final Retry: After 1 hour

Webhooks are considered failed if:

Your endpoint returns a non-2xx status code
Connection timeout (30 seconds)
SSL/TLS errors

Best Practices

1. Idempotency

Idempotent Webhook Handler

async function handleWebhook(request) {
const deliveryId = request.headers['x-unizo-delivery-id'];

// Check if already processed
if (await isProcessed(deliveryId)) {
  return { status: 200, message: 'Already processed' };
}

// Process webhook
await processWebhook(request.body);

// Mark as processed
await markProcessed(deliveryId);

return { status: 200 };
}

2. Async Processing

Asynchronous Processing

app.post('/webhooks/observability', (req, res) => {
// Validate signature
if (!verifySignature(req)) {
  return res.status(401).send('Invalid signature');
}

// Queue for processing
alertQueue.add(req.body);

// Return immediately
res.status(200).send('OK');
});

3. Alert Routing

Intelligent Alert Routing

async function processAlert(payload) {
const { alert, integration } = payload;

// Route based on severity and tags
if (alert.severity === 'critical') {
  await notifyPagerDuty(alert);
  await createIncident(alert);
} else if (alert.tags.includes('database')) {
  await notifyDatabaseTeam(alert);
} else {
  await notifySlackChannel(alert);
}

// Log for audit
await logAlert(payload);
}

Need Help?

For webhook-related support:

Contact support at support@unizo.ai

Supported Event Types​

Webhook Security

Headers

Signature Verification

Event Details​

Alert Events​

Alert Triggered

alert:triggered

Headers

Request Body Schema

Example Payload

Response

Alert Resolved

alert:resolved

Headers

Request Body Schema

Example Payload

Response

Alert Acknowledged

alert:acknowledged

Headers

Request Body Schema

Example Payload

Response

Monitor Events​

Monitor Created

monitor:created

Headers

Request Body Schema

Example Payload

Response

Dashboard Events​

Dashboard Created

dashboard:created

Headers

Request Body Schema

Example Payload

Response

Anomaly Events​

Anomaly Detected

metric:anomaly_detected

Headers

Request Body Schema

Example Payload

Response

Webhook Delivery & Retries​

Best Practices​

1. Idempotency​

Idempotent Webhook Handler

2. Async Processing​

Asynchronous Processing

3. Alert Routing​

Intelligent Alert Routing

Need Help?​

Supported Event Types

Event Details

Alert Events

`alert:triggered`

`alert:resolved`

`alert:acknowledged`

Monitor Events

`monitor:created`

Dashboard Events

`dashboard:created`

Anomaly Events

`metric:anomaly_detected`

Webhook Delivery & Retries

Best Practices

1. Idempotency

2. Async Processing

3. Alert Routing

Need Help?