Real-time Events

Webhooks & Events

Subscribe to governance events and receive HMAC-signed webhook deliveries in real-time.

Event System

Every action in DRD generates an event that is added to the hash-chained audit log. Events are the foundation of the reputation system and enforcement triggers.

Event Types

Event	Description
agent.registered	New agent registered
policy.evaluated	Policy check completed
policy.denied	Action blocked by policy
enforcement.created	Enforcement action applied
enforcement.appealed	Agent appealed enforcement
approval.requested	Operator approval needed
approval.decided	Approval approved/denied
reputation.updated	Agent reputation recalculated
badge.earned	Trust badge awarded
badge.revoked	Trust badge removed

Hash-Chained Audit Log

Each event stores a chain hash for tamper-evident auditing. Every event links to the previous, creating an immutable chain. Hash chain integrity is verified every 6 hours automatically.

Event N-2

SHA-256

→

Event N-1

SHA-256

→

Event N

SHA-256

hash-chain.ts

chainHash = SHA-256(previousHash + eventType + data + timestamp)

// Each event links to the previous, creating an immutable chain
// Hash chain integrity is verified every 6 hours automatically

Server-Sent Events (SSE)

The dashboard uses SSE for real-time event streaming. You can also consume the stream directly.

sse-client.ts

const eventSource = new EventSource(
  'https://api.drd.io/api/v1/events/stream',
  { headers: { 'Authorization': 'Bearer drd_live_sk_...' } }
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data.type, data.payload);
};

Webhook Configuration

webhook-config.ts

POST /api/v1/webhooks
{
  "url": "https://your-server.com/drd-webhook",
  "events": ["enforcement.created", "approval.requested"],
  "secret": "whsec_..." // Optional: auto-generated if omitted
}

Webhook Verification

All webhook deliveries are signed with HMAC-SHA256. Verify the signature to ensure the payload is authentic.

verify-webhook.ts

import crypto from 'crypto';

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

// In your webhook handler:
app.post('/drd-webhook', (req, res) => {
  const signature = req.headers['x-drd-signature'];
  if (!verifyWebhook(req.rawBody, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  // Process the event...
});

Retry Policy

Max retries

5 attempts

Backoff

Exponential (1s, 2s, 4s, 8s, 16s)

Timeout

10 seconds per delivery

Success

Any 2xx response code

Failure

After 5 failed attempts, webhook is disabled

Next Steps

API Reference

Webhook management endpoints

Learn more →

Agent Governance

Enforcement event triggers

Learn more →

SDK Guide

Report events from your agent

Learn more →

Event

Description

agent.registered

New agent registered

policy.evaluated

Policy check completed

policy.denied

Action blocked by policy

enforcement.created

Enforcement action applied

enforcement.appealed

Agent appealed enforcement

approval.requested

Operator approval needed

approval.decided

Approval approved/denied

reputation.updated

Agent reputation recalculated

badge.earned

Trust badge awarded

badge.revoked

Trust badge removed

const eventSource = new EventSource( 'https://api.drd.io/api/v1/events/stream', { headers: { 'Authorization': 'Bearer drd_live_sk_...' } } ); eventSource.onmessage = (event) => { const data = JSON.parse(event.data); console.log(data.type, data.payload); };

import crypto from 'crypto'; function verifyWebhook(payload: string, signature: string, secret: string) { const expected = crypto .createHmac('sha256', secret) .update(payload) .digest('hex'); return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(expected) ); } // In your webhook handler: app.post('/drd-webhook', (req, res) => { const signature = req.headers['x-drd-signature']; if (!verifyWebhook(req.rawBody, signature, WEBHOOK_SECRET)) { return res.status(401).send('Invalid signature'); } // Process the event... });