Webhook Setup

Overview

GOVERN can push governance events to your systems in real-time via webhooks. When an inference is flagged or blocked, or when drift is detected, GOVERN sends an HTTP POST to your configured endpoint within seconds.

Creating a webhook

1. Go to govern.archetypal.ai
2. Navigate to Settings → Webhooks → New Webhook
3. Enter your endpoint URL
4. Select the events you want to receive
5. Copy the signing secret

Or via API:

curl -X POST https://api.govern.archetypal.ai/v1/webhooks \
  -H "Authorization: Bearer gvn_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/govern",
    "events": ["inference.flagged", "inference.blocked", "drift.sustained"],
    "description": "Production governance alerts"
  }'

Response:

{
  "webhook_id": "wh_01HXYZ",
  "url": "https://your-app.com/webhooks/govern",
  "events": ["inference.flagged", "inference.blocked", "drift.sustained"],
  "signing_secret": "whsec_xxxxxxxxxxxx",
  "created_at": "2026-04-12T14:23:00.000Z"
}

Store the signing_secret securely. It is shown only once.

Webhook endpoint requirements

Your endpoint must:

1. Accept POST requests
2. Return 200 OK within 5 seconds
3. Accept the application/json content type
4. Handle the X-Govern-Signature-256 header for verification (see Webhook Security)

// Express.js example
app.post('/webhooks/govern', express.raw({ type: 'application/json' }), (req, res) => {
  // Verify signature first
  const verified = govern.webhooks.verify(req.rawBody, req.headers['x-govern-signature-256']);
  if (!verified) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);

  // Process asynchronously — respond immediately
  processGovernEvent(event).catch(console.error);

  res.status(200).send('OK');
});

Caution

Always return 200 before doing your processing. If your endpoint takes longer than 5 seconds to respond, GOVERN marks the delivery as failed and retries. Long-running processing should be done asynchronously.

Retry behavior

Failed deliveries are retried with exponential backoff:

Attempt	Wait
Initial	Immediate
Retry 1	5 minutes
Retry 2	30 minutes
Retry 3	2 hours
Retry 4	8 hours
Give up	After 4 retries (total: ~10 hours)

A delivery is considered failed if:

• The endpoint returns a non-2xx status
• The endpoint times out (5 seconds)
• The endpoint is unreachable

Testing webhooks

Use the test button in the dashboard to send a sample event to your endpoint:

Settings → Webhooks → [webhook name] → Send Test Event

Or via CLI:

govern webhooks test wh_01HXYZ --event inference.flagged

Built-in integrations

GOVERN has native integrations for common destinations:

Destination	Setup
Slack	Settings → Integrations → Slack
PagerDuty	Settings → Integrations → PagerDuty
Microsoft Teams	Settings → Integrations → Teams
Datadog	Settings → Integrations → Datadog
Splunk	Settings → Integrations → Splunk

These use the webhook system internally but provide richer formatting and no custom endpoint required.