Receive real-time notifications about anomalies, alerts, and system events
Webhooks allow your application to receive real-time notifications when events occur in your Perimi account. Instead of polling our API, webhooks push data to your application as soon as events happen.
Triggered when an anomaly is detected in a video stream
{
"event": "anomaly.detected",
"timestamp": "2024-09-14T15:30:00Z",
"stream_id": "stream_123",
"anomaly": {
"id": "anomaly_456",
"type": "motion_detection",
"confidence": 0.92,
"bounding_box": {
"x": 150, "y": 200,
"width": 100, "height": 120
},
"image_url": "https://storage.perimi.ai/anomalies/456.jpg"
}
}Triggered when a stream goes online, offline, or encounters an error
{
"event": "stream.status_changed",
"timestamp": "2024-09-14T15:30:00Z",
"stream_id": "stream_123",
"status": {
"previous": "online",
"current": "offline",
"reason": "connection_timeout",
"error_message": "RTSP timeout after 30 seconds"
}
}Triggered when an alert rule matches detected activity
{
"event": "alert.triggered",
"timestamp": "2024-09-14T15:30:00Z",
"stream_id": "stream_123",
"alert": {
"id": "alert_789",
"rule_name": "After Hours Motion",
"severity": "high",
"zone": "entrance",
"anomaly_count": 3
}
}Set up your endpoint to receive webhook notifications
curl -X POST "https://api.perimi.ai/v1/webhooks" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-app.com/webhook",
"events": ["anomaly.detected", "stream.status_changed"],
"secret": "your_webhook_secret"
}'Validate incoming webhook requests for security
// Example verification (Node.js)
const crypto = require('crypto');
function verifyWebhook(payload, signature, secret) {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(payload, 'utf8')
.digest('hex');
return signature === 'sha256=' + expectedSignature;
}Process different event types in your application
// Example webhook handler (Node.js/Express)
app.post('/webhook', (req, res) => {
const event = req.body;
switch(event.event) {
case 'anomaly.detected':
handleAnomalyDetected(event);
break;
case 'stream.status_changed':
handleStreamStatusChanged(event);
break;
case 'alert.triggered':
handleAlertTriggered(event);
break;
}
res.status(200).send('OK');
});Tips for testing webhook integration and troubleshooting issues
Expose local development server for testing
Capture and inspect webhook payloads
Use API to trigger test events
Endpoint must respond within 10 seconds
Ensure valid HTTPS certificate
Check webhook secret and signature calculation
Start receiving real-time notifications in your application