Skip to content

Webhooks ​

Receive real-time notifications for events.

Overview ​

Webhooks allow your application to receive HTTP callbacks when events occur in GhostAI.

Supported Events ​

EventDescription
pii.detectedPII detected in message
code.detectedCode/secrets detected
chat.completedChat message completed
session.createdNew session started
session.endedSession closed
export.completedExport ready for download
user.invitedTeam member invited
user.joinedTeam member joined
alert.triggeredSecurity alert triggered
connector.connectedSaaS tool connected
connector.disconnectedConnection revoked
connector.sync_completedConnector sync finished
connector.sync_failedConnector sync failed
connector.health_degradedConnection health worsened

Creating a Webhook ​

POST /api/webhooks

Request ​

json
{
  "url": "https://yourapp.com/webhooks/ghostai",
  "events": ["pii.detected", "code.detected"],
  "secret": "your-webhook-secret",
  "enabled": true
}
FieldTypeRequiredDescription
urlstringYesYour webhook endpoint
eventsarrayYesEvents to subscribe to
secretstringNoSigning secret
enabledbooleanNoEnable webhook

Response ​

json
{
  "id": "wh_abc123",
  "url": "https://yourapp.com/webhooks/ghostai",
  "events": ["pii.detected", "code.detected"],
  "enabled": true,
  "created_at": "2024-01-15T10:00:00Z"
}

Webhook Payload ​

Headers ​

Content-Type: application/json
X-GhostAI-Signature: sha256=abc123...
X-GhostAI-Timestamp: 1705312800
X-GhostAI-Event: pii.detected
X-GhostAI-Delivery: del_xyz789

Body ​

json
{
  "id": "evt_abc123",
  "type": "pii.detected",
  "created": "2024-01-15T10:30:00Z",
  "data": {
    "session_id": "sess_xyz",
    "message_id": "msg_123",
    "entities": [
      {
        "type": "US_SSN",
        "confidence": 0.99,
        "compliance": ["HIPAA"]
      }
    ],
    "pii_count": 1
  }
}

Verifying Signatures ​

Always verify webhook signatures to ensure authenticity.

Node.js Example ​

javascript
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return `sha256=${expectedSignature}` === signature;
}

// In your webhook handler
app.post('/webhooks/ghostai', (req, res) => {
  const signature = req.headers['x-ghostai-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifyWebhook(payload, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process webhook
  const event = req.body;
  console.log('Received:', event.type);
  
  res.status(200).send('OK');
});

Python Example ​

python
import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return f"sha256={expected}" == signature

@app.route('/webhooks/ghostai', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-GhostAI-Signature')
    payload = request.get_data(as_text=True)
    
    if not verify_webhook(payload, signature, WEBHOOK_SECRET):
        return 'Invalid signature', 401
    
    event = request.json
    print(f"Received: {event['type']}")
    
    return 'OK', 200

Event Details ​

pii.detected ​

json
{
  "type": "pii.detected",
  "data": {
    "session_id": "sess_abc",
    "message_id": "msg_123",
    "user_id": "user_456",
    "entities": [
      {
        "type": "US_SSN",
        "confidence": 0.99,
        "token": "[US_SSN_x1y2]",
        "compliance": ["HIPAA", "PCI-DSS"]
      }
    ],
    "pii_count": 1,
    "tokenized": true
  }
}

code.detected ​

json
{
  "type": "code.detected",
  "data": {
    "session_id": "sess_abc",
    "message_id": "msg_456",
    "language": "javascript",
    "secrets_found": 2,
    "action_taken": "warned",
    "secrets": [
      {
        "type": "API_KEY",
        "provider": "openai"
      }
    ]
  }
}

alert.triggered ​

json
{
  "type": "alert.triggered",
  "data": {
    "alert_type": "exfiltration_attempt",
    "severity": "high",
    "user_id": "user_789",
    "details": {
      "method": "base64",
      "entity_type": "US_SSN"
    }
  }
}

Managing Webhooks ​

List Webhooks ​

GET /api/webhooks

Get Webhook ​

GET /api/webhooks/{webhook_id}

Update Webhook ​

PUT /api/webhooks/{webhook_id}

Delete Webhook ​

DELETE /api/webhooks/{webhook_id}

Test Webhook ​

POST /api/webhooks/{webhook_id}/test

Sends a test event to verify your endpoint.

Retry Policy ​

Failed webhooks are retried with exponential backoff:

AttemptDelay
1Immediate
21 minute
35 minutes
430 minutes
52 hours

After 5 failures, the webhook is disabled.

SIEM Integration ​

SIEM integration provides a more comprehensive event streaming system compared to raw webhooks, with 70+ event types, pre-built SIEM presets, compliance tagging, and tamper-evident hash chains. For enterprise SIEM integration with 15+ pre-built connectors, see SIEM Integration.

Best Practices ​

  1. Verify signatures: Always validate webhook authenticity
  2. Respond quickly: Return 2xx within 30 seconds
  3. Process async: Queue events for background processing
  4. Handle duplicates: Events may be sent more than once
  5. Monitor failures: Set up alerts for webhook errors

SOC 2 Type II Certified | BAA Available | HIPAA-Ready