Webhooks

Real-time event notifications via webhooks. Integrate Knowledge Tree events with your CI/CD, chat, and monitoring workflows.

Overview

Webhooks provide real-time event notifications from Knowledge Tree. When a resource is discovered, a change is detected, or a finding is created, Knowledge Tree sends an HTTP POST request to your configured webhook endpoints. This enables event-driven integrations with your existing toolchain.

Events

Event type	Trigger
`resource.created`	A new resource is discovered
`resource.updated`	An existing resource's attributes change
`resource.deleted`	A resource is no longer found
`relationship.created`	A new relationship between resources is detected
`relationship.deleted`	A relationship is removed
`discovery.started`	A discovery run begins
`discovery.completed`	A discovery run completes
`discovery.failed`	A discovery run fails
`finding.created`	A new finding (policy violation, anomaly) is created
`finding.resolved`	A finding is resolved

Payload format

{
  "id": "evt_abc123",
  "type": "resource.created",
  "timestamp": "2025-06-01T12:00:00Z",
  "scope": "production",
  "data": {
    "resource": {
      "id": "i-abc123",
      "type": "aws_ec2_instance",
      "provider": "aws",
      "properties": {
        "instance_type": "t3.large",
        "region": "us-east-1"
      },
      "tags": {
        "Environment": "production",
        "Owner": "platform"
      }
    }
  }
}

Delivery guarantees

Webhooks are delivered with at-least-once guarantees. If an endpoint fails to acknowledge the delivery (200-299 response), Knowledge Tree retries with exponential backoff:

Retry schedule -- 10s, 30s, 1m, 5m, 15m, 30m, 1h
Max retries -- 7 attempts before the webhook is marked as failed
Dead letter queue -- failed deliveries are stored for manual replay
Timeout -- each delivery attempt times out after 30 seconds

Idempotent handlers

Since webhooks use at-least-once delivery, your handlers should be idempotent. Use the event id field for deduplication.

Configuration

# config.yaml
webhooks:
  endpoints:
    - url: https://hooks.slack.com/services/xxx
      events:
        - discovery.completed
        - discovery.failed
      secret: ${WEBHOOK_SECRET}
    - url: https://api.acme.com/kt-webhook
      events:
        - resource.created
        - resource.updated
        - resource.deleted
      secret: ${ACME_WEBHOOK_SECRET}
      retry:
        max_attempts: 10
        backoff: exponential

Signing

Webhook payloads are signed using HMAC-SHA256. Your endpoint should verify the signature before processing:

// Verify webhook signature (Node.js example)
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(JSON.stringify(payload));
  const expected = 'sha256=' + hmac.digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}