Documentation

PolicyCortex Webhooks API: Real-Time Policy & Compliance Alerts

Configure real-time event notifications using webhooks to receive instant updates about policy violations, compliance changes, and governance events.

PolicyCortex Webhooks API: Installation, Configuration & Quick Start

Quick Start

Create Webhook Endpoint

Register a webhook endpoint to receive real-time notifications from PolicyCortex.

Create Webhookbash
curl -X POST https://api.policycortex.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/policycortex",
    "events": [
      "policy.violation.created",
      "policy.violation.resolved",
      "compliance.status.changed"
    ],
    "secret": "your-webhook-secret",
    "active": true
  }'

Event Types

🚨 Policy Events

Policy violation and compliance events

• policy.violation.created
• policy.violation.resolved
• policy.deployment.completed
• policy.enforcement.failed

📊 Compliance Events

Compliance status and reporting events

• compliance.status.changed
• compliance.report.generated
• compliance.audit.started
• compliance.framework.updated

🔍 Scan Events

Resource scanning and discovery events

• scan.completed
• scan.failed
• resource.discovered
• resource.changed

👥 User Events

User activity and authentication events

• user.login
• user.policy.exemption
• user.role.changed
• api.key.created

Webhook Security

Signature Verification

All webhook payloads are signed with HMAC-SHA256 to ensure authenticity and integrity.

Verify Webhook Signaturejavascript
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  const computedSignature = 'sha256=' + expectedSignature;

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(computedSignature)
  );
}

app.use('/webhooks/policycortex', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-policycortex-signature'];
  const payload = req.body;

  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Unauthorized');
  }

  const event = JSON.parse(payload);
  console.log('Received webhook:', event.type);

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

Security Best Practices

  • • Always verify webhook signatures
  • • Use HTTPS endpoints only
  • • Store secrets securely
  • • Implement replay attack protection
  • • Log all webhook requests

Delivery Guarantees

  • • At-least-once delivery
  • • Automatic retry on failure
  • • 24-hour retry window
  • • Exponential backoff strategy
  • • Event ordering preserved

Payload Examples

Policy Violation Event

policy.violation.created Eventjson
{
  "id": "evt_1234567890abcdef",
  "type": "policy.violation.created",
  "created": "2024-01-15T14:30:00Z",
  "data": {
    "violation": {
      "id": "viol_abcdef1234567890",
      "policy_id": "pol_567890abcdef1234",
      "policy_name": "require-s3-encryption",
      "resource_id": "arn:aws:s3:::my-bucket",
      "resource_type": "AWS::S3::Bucket",
      "severity": "HIGH",
      "status": "OPEN",
      "message": "S3 bucket must have encryption enabled",
      "detected_at": "2024-01-15T14:29:45Z",
      "account_id": "123456789012",
      "region": "us-east-1",
      "tags": {
        "environment": "production",
        "team": "platform"
      },
      "compliance_frameworks": ["SOC2", "HIPAA"]
    }
  }
}

Compliance Status Event

compliance.status.changed Eventjson
{
  "id": "evt_fedcba0987654321",
  "type": "compliance.status.changed",
  "created": "2024-01-15T14:35:00Z",
  "data": {
    "compliance": {
      "framework": "SOC2",
      "account_id": "123456789012",
      "previous_score": 87.5,
      "current_score": 92.3,
      "status": "COMPLIANT",
      "previous_status": "NON_COMPLIANT",
      "changed_controls": [
        {
          "control_id": "CC6.1",
          "control_name": "Logical access security measures",
          "previous_status": "FAILED",
          "current_status": "PASSED",
          "reason": "S3 encryption policy violations resolved"
        }
      ],
      "assessment_date": "2024-01-15T14:30:00Z"
    }
  }
}

Scan Completed Event

scan.completed Eventjson
{
  "id": "evt_scan1234567890",
  "type": "scan.completed",
  "created": "2024-01-15T15:00:00Z",
  "data": {
    "scan": {
      "id": "scan_abc123def456",
      "name": "Production Compliance Scan",
      "status": "completed",
      "started_at": "2024-01-15T14:30:00Z",
      "completed_at": "2024-01-15T15:00:00Z",
      "duration": "30m",
      "resources_scanned": 5432,
      "violations_found": 23,
      "compliance_score": 94.7
    }
  }
}

Webhook Management

GET/v1/webhooks

List all configured webhooks.

List Webhooksbash
curl -X GET https://api.policycortex.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY"
GET/v1/webhooks/:id

Retrieve details of a specific webhook.

Get Webhookbash
curl -X GET https://api.policycortex.com/v1/webhooks/wh_123 \
  -H "Authorization: Bearer YOUR_API_KEY"
PUT/v1/webhooks/:id

Update an existing webhook.

Update Webhookbash
curl -X PUT https://api.policycortex.com/v1/webhooks/wh_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "active": false,
    "events": ["policy.violation.created"]
  }'
DELETE/v1/webhooks/:id

Delete a webhook endpoint.

Delete Webhookbash
curl -X DELETE https://api.policycortex.com/v1/webhooks/wh_123 \
  -H "Authorization: Bearer YOUR_API_KEY"
POST/v1/webhooks/:id/test

Send a test event to your webhook.

Test Webhookbash
curl -X POST https://api.policycortex.com/v1/webhooks/wh_123/test \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type": "policy.violation.created"}'

Webhook Configuration

Configuration Options

Webhook Configurationjson
{
  "url": "https://your-app.com/webhooks/policycortex",
  "events": [
    "policy.violation.created",
    "compliance.status.changed"
  ],
  "secret": "your-webhook-secret",
  "active": true,
  "filters": {
    "severity": ["HIGH", "CRITICAL"],
    "environments": ["production"],
    "cloud_providers": ["aws", "azure"]
  },
  "retry_config": {
    "max_attempts": 3,
    "backoff_multiplier": 2
  },
  "timeout_seconds": 30,
  "headers": {
    "X-Custom-Header": "custom-value"
  }
}

Required Fields

  • url: HTTPS endpoint URL
  • events: Array of event types
  • secret: Signature secret key

Optional Fields

  • filters: Event filtering criteria
  • retry_config: Retry behavior
  • headers: Custom HTTP headers

Troubleshooting

Common Issues

  • • Endpoint returns non-2xx status
  • • Signature verification fails
  • • Timeout exceeds 30 seconds
  • • SSL certificate invalid
  • • Firewall blocking requests

Debugging Tips

  • • Check webhook logs in dashboard
  • • Use test endpoint to verify setup
  • • Monitor response times
  • • Validate signature implementation
  • • Review retry attempts