Webhooks

Push governance events to external systems with HMAC signing, retry logic, and event filtering.

Webhooks push governance events to external systems in real-time: Slack, PagerDuty, SIEM, or any HTTP endpoint. Payloads are HMAC-SHA256 signed and delivered with exponential backoff retry.

Setup

import { createWebhookRegistry } from '@lua-ai-global/governance-enterprise';

const webhooks = createWebhookRegistry({
  tenantId: 'org_acme',
  maxAttempts: 3,       // default
  retryDelayMs: 1000,   // base delay, exponential backoff
});

Register an Endpoint

const endpoint = await webhooks.register({
  url: 'https://hooks.slack.com/services/...',
  events: ['enforcement.blocked', 'incident.opened', 'agent.killed'],
  secret: 'whsec_your_signing_secret',
});

// endpoint:
// {
//   id: 'wh_abc123',
//   tenantId: 'org_acme',
//   url: 'https://hooks.slack.com/services/...',
//   events: ['enforcement.blocked', 'incident.opened', 'agent.killed'],
//   enabled: true,
//   createdAt: '2026-03-10T14:30:00Z',
// }

Deliver Events

const records = await webhooks.deliver({
  type: 'enforcement.blocked',
  agentId: 'rogue-agent-42',
  tool: 'shell_exec',
  reason: "Tool 'shell_exec' is blocked by policy",
  timestamp: new Date().toISOString(),
});

// Delivered to all endpoints subscribed to 'enforcement.blocked'
// records: [
//   {
//     endpointId: 'wh_abc123',
//     status: 'success',
//     httpStatus: 200,
//     attempts: 1,
//     latencyMs: 142,
//   },
// ]

HMAC Signing

When a secret is configured on an endpoint, every payload is HMAC-SHA256 signed. The signature is sent in the X-Governance-Signature header:

X-Governance-Signature: sha256=a3f8c1d2e4b5...

Verify on the receiving end:

import { createHmac } from 'node:crypto';

function verifySignature(payload: string, signature: string, secret: string): boolean {
  const expected = 'sha256=' + createHmac('sha256', secret).update(payload).digest('hex');
  return expected === signature;
}

Event Types

Event	Trigger
`enforcement.allowed`	Agent action passed policy evaluation
`enforcement.blocked`	Agent action blocked by policy
`incident.opened`	New incident created
`incident.resolved`	Incident resolved
`agent.registered`	New agent registered
`agent.killed`	Agent killed via kill switch
`agent.revived`	Agent revived after kill
`score.changed`	Agent governance score changed

Manage Endpoints

const endpoints = await webhooks.listEndpoints();

await webhooks.disable('wh_abc123');
await webhooks.enable('wh_abc123');
await webhooks.unregister('wh_abc123');

const endpoint = await webhooks.getEndpoint('wh_abc123');

Delivery Logs

const logs = await webhooks.getLogs('wh_abc123');
// [
//   {
//     endpointId: 'wh_abc123',
//     eventType: 'enforcement.blocked',
//     status: 'success',
//     httpStatus: 200,
//     attempts: 1,
//     latencyMs: 142,
//     deliveredAt: '2026-03-10T14:31:00Z',
//   },
//   {
//     status: 'failed',
//     httpStatus: 503,
//     attempts: 3,
//     error: 'Service temporarily unavailable',
//   },
// ]

Custom Filters

Filter events beyond just type matching:

await webhooks.register({
  url: 'https://pagerduty.com/integration/...',
  events: ['incident.opened'],
  filter: { severity: ['critical', 'high'] },
  secret: 'whsec_...',
});

Only critical and high severity incidents will be delivered to this endpoint.