Webhooks

Triggered when content violates a configured policy rule. Includes policy details, violation type, and severity.

Triggered when personally identifiable information is detected in content. Includes detected entity types and confidence scores.

Triggered when an AI agent action is blocked by governance rules. Includes the blocked action and reason.

Triggered when a request requires human review before proceeding.

Triggered when a human reviewer approves a pending request.

Triggered when a human reviewer rejects a pending request.

Triggered when a circuit breaker opens due to repeated failures, temporarily blocking requests.

Triggered when rate limits are exceeded for an API key or IP address.

Triggered for security-related events such as suspicious activity or authentication anomalies.

curl -X POST https://api.tork.network/v1/webhooks \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Alerts",
    "url": "https://your-server.com/webhook",
    "events": [
      "policy.violation",
      "pii.detected",
      "security.alert"
    ]
  }'

{
  "id": "wh_abc123",
  "name": "Production Alerts",
  "url": "https://your-server.com/webhook",
  "events": ["policy.violation", "pii.detected", "security.alert"],
  "secret": "whsec_a1b2c3d4e5f6...",
  "is_active": true,
  "created_at": "2026-01-21T12:00:00Z",
  "message": "Webhook created. Save the secret - it will not be shown again."
}

Store your webhook secret in a secure environment variable. Never commit it to source control or expose it in client-side code.

{
  "id": "evt_xyz789",
  "event": "policy.violation",
  "timestamp": "2026-01-21T12:30:45Z",
  "organization_id": "org_abc123",
  "data": {
    "policy_id": "pol_001",
    "policy_name": "PII Protection Policy",
    "violation_type": "pii_detected",
    "severity": "high",
    "content_preview": "The user's SSN is...",
    "agent_id": "agent_456",
    "request_id": "req_789",
    "metadata": {
      "detected_entities": ["ssn", "phone_number"],
      "confidence": 0.95
    }
  }
}

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret, tolerance = 300) {
  const parts = signature.split(',');
  const timestamp = parseInt(parts.find(p => p.startsWith('t='))?.replace('t=', '') || '0');
  const sig = parts.find(p => p.startsWith('v1='))?.replace('v1=', '') || '';

  // Check timestamp tolerance (default 5 minutes)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > tolerance) {
    throw new Error('Webhook timestamp too old');
  }

  // Compute expected signature
  const signedPayload = `${timestamp}.${payload}`;
  const expectedSig = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  // Constant-time comparison
  if (!crypto.timingSafeEqual(Buffer.from(sig, 'hex'), Buffer.from(expectedSig, 'hex'))) {
    throw new Error('Invalid webhook signature');
  }

  return true;
}

// Express.js example
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-tork-signature'];
  const payload = req.body.toString();

  try {
    verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET);
    const event = JSON.parse(payload);

    // Handle the event
    switch (event.event) {
      case 'policy.violation':
        handlePolicyViolation(event.data);
        break;
      case 'pii.detected':
        handlePiiDetected(event.data);
        break;
      // ... handle other events
    }

    res.status(200).json({ received: true });
  } catch (err) {
    console.error('Webhook error:', err.message);
    res.status(400).json({ error: err.message });
  }
});