Appearance
Webhooks
Receive real-time notifications for events.
Overview
Webhooks allow your application to receive HTTP callbacks when events occur in GhostAI.
Supported Events
| Event | Description |
|---|---|
pii.detected | PII detected in message |
code.detected | Code/secrets detected |
chat.completed | Chat message completed |
session.created | New session started |
session.ended | Session closed |
export.completed | Export ready for download |
user.invited | Team member invited |
user.joined | Team member joined |
alert.triggered | Security alert triggered |
connector.connected | SaaS tool connected |
connector.disconnected | Connection revoked |
connector.sync_completed | Connector sync finished |
connector.sync_failed | Connector sync failed |
connector.health_degraded | Connection health worsened |
Creating a Webhook
POST /api/webhooksRequest
json
{
"url": "https://yourapp.com/webhooks/ghostai",
"events": ["pii.detected", "code.detected"],
"secret": "your-webhook-secret",
"enabled": true
}| Field | Type | Required | Description |
|---|---|---|---|
url | string | Yes | Your webhook endpoint |
events | array | Yes | Events to subscribe to |
secret | string | No | Signing secret |
enabled | boolean | No | Enable 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_xyz789Body
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', 200Event 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/webhooksGet 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}/testSends a test event to verify your endpoint.
Retry Policy
Failed webhooks are retried with exponential backoff:
| Attempt | Delay |
|---|---|
| 1 | Immediate |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 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
- Verify signatures: Always validate webhook authenticity
- Respond quickly: Return 2xx within 30 seconds
- Process async: Queue events for background processing
- Handle duplicates: Events may be sent more than once
- Monitor failures: Set up alerts for webhook errors