Webhook Types

Type definitions for webhook events.

WebhookEventType

Available webhook event types.

type WebhookEventType = 
  | 'risk.created'
  | 'risk.updated'
  | 'risk.deleted'
  | 'risk.reviewed'
  | 'asset.created'
  | 'asset.updated'
  | 'asset.deleted'
  | 'asset.reviewed'
  | 'task.created'
  | 'task.assigned'
  | 'task.completed'
  | 'task.overdue'
  | 'document.created'
  | 'document.updated'
  | 'document.expired'
  | 'user.created'
  | 'user.updated'
  | 'user.deactivated'
  | 'compliance.status_changed'
  | 'audit.completed';

WebhookEvent

Structure of a webhook event payload.

interface WebhookEvent<T = unknown> {
  id: string;
  type: WebhookEventType;
  apiVersion: string;
  createdAt: string;
  tenantId: string;
  data: {
    object: T;
    previousAttributes?: Partial<T>;
  };
  metadata?: {
    correlationId?: string;
    triggeredBy?: string;
    source?: string;
  };
}

Properties

Property	Type	Description
id	string	Unique event ID
type	WebhookEventType	Event type
apiVersion	string	API version
createdAt	string	ISO timestamp
tenantId	string	Tenant/organization ID
data.object	T	The affected resource
data.previousAttributes	Partial<T>	Changed fields (for updates)
metadata.correlationId	string	Correlation ID for tracing
metadata.triggeredBy	string	User who triggered the event
metadata.source	string	Event source

WebhookSubscription

Webhook subscription configuration.

interface WebhookSubscription {
  id: string;
  url: string;
  events: WebhookEventType[];
  status: 'active' | 'disabled';
  secret: string;
  createdAt: Date;
  updatedAt: Date;
}

Event Handling Example

import { WebhookEvent, Risk, Task, Document } from '@deiterate/sdk';
import crypto from 'crypto';

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

// Handle webhook event
function handleWebhook(event: WebhookEvent) {
  console.log(`Received event: ${event.type}`);
  console.log(`Event ID: ${event.id}`);
  console.log(`Timestamp: ${event.createdAt}`);
  
  switch (event.type) {
    case 'risk.created': {
      const risk = event.data.object as Risk;
      console.log(`New risk: ${risk.risk}`);
      break;
    }
    
    case 'risk.updated': {
      const risk = event.data.object as Risk;
      const changed = event.data.previousAttributes;
      console.log(`Risk updated: ${risk.id}`);
      console.log(`Changed fields:`, Object.keys(changed || {}));
      break;
    }
    
    case 'task.completed': {
      const task = event.data.object as Task;
      console.log(`Task completed: ${task.description}`);
      break;
    }
    
    case 'task.overdue': {
      const task = event.data.object as Task;
      console.log(`Task overdue: ${task.description}`);
      // Send notification
      break;
    }
    
    case 'document.expired': {
      const doc = event.data.object as Document;
      console.log(`Document expired: ${doc.fileName}`);
      // Trigger review workflow
      break;
    }
    
    case 'audit.completed': {
      console.log('Audit completed');
      // Generate report
      break;
    }
    
    default:
      console.log(`Unhandled event type: ${event.type}`);
  }
}

// Express.js webhook endpoint
app.post('/webhooks/deiterate', (req, res) => {
  const signature = req.headers['x-deiterate-signature'] as string;
  const payload = JSON.stringify(req.body);
  
  if (!verifySignature(payload, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = req.body as WebhookEvent;
  handleWebhook(event);
  
  res.status(200).send('OK');
});

Event Categories

Risk Events

Event	Trigger
risk.created	New risk added
risk.updated	Risk modified
risk.deleted	Risk deleted
risk.reviewed	Risk marked as reviewed

Asset Events

Event	Trigger
asset.created	New asset added
asset.updated	Asset modified
asset.deleted	Asset deleted
asset.reviewed	Asset marked as reviewed

Task Events

Event	Trigger
task.created	New task created
task.assigned	Task assigned to user
task.completed	Task marked complete
task.overdue	Task passed due date

Document Events

Event	Trigger
document.created	New document uploaded
document.updated	Document modified
document.expired	Document review date passed

User Events

Event	Trigger
user.created	New user added
user.updated	User modified
user.deactivated	User deactivated

Other Events

Event	Trigger
compliance.status_changed	Compliance status changed
audit.completed	Audit marked complete