Webhooks

Set up real-time event notifications with webhooks.

Overview

Webhooks allow your application to receive real-time notifications when events occur in de.iterate. Instead of polling the API for changes, webhooks push data to your application as events happen.

Setting Up Webhooks

const webhook = await client.webhooks.create({
  url: 'https://your-app.com/webhooks/deiterate',
  events: ['risk.created', 'risk.updated', 'task.overdue'],
  secret: 'your-webhook-secret',
});

Available Events

Event	Description
risk.created	A new risk was added
risk.updated	A risk was modified
risk.deleted	A risk was removed
risk.reviewed	A risk was marked as reviewed
asset.created	A new asset was added
asset.updated	An asset was modified
asset.deleted	An asset was removed
asset.reviewed	An asset was marked as reviewed
task.created	A new task was created
task.assigned	A task was assigned
task.completed	A task was completed
task.overdue	A task became overdue
document.created	A document was uploaded
document.updated	A document was modified
document.expired	A document's review date passed
audit.completed	An audit was completed

Verifying Webhook Signatures

Always verify webhook signatures to ensure requests are from de.iterate:

import crypto from 'crypto';

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));
}

Webhook Payload Structure

interface WebhookEvent {
  id: string;
  type: string;
  createdAt: string;
  data: {
    object: any;
    previousAttributes?: any;
  };
}

Best Practices

1. Respond quickly - Return a 200 status within 5 seconds
2. Process asynchronously - Queue events for background processing
3. Handle retries - Webhooks are retried on failure
4. Verify signatures - Always validate the webhook signature
5. Use HTTPS - Only use secure endpoints

Next Steps

• Webhook Examples - Complete implementation examples
• WebhooksResource API - Full API reference