Core API
Webhooks
Receive real-time notifications when escalation-worthy events occur in your Safety evaluations or Observe monitoring.
Overview
DeepaData webhooks deliver POST requests to your configured endpoint whenever a Safety evaluation or Observe observation triggers an escalation signal. Use webhooks to power real-time alerts, incident response workflows, or dashboard integrations.
Configuration: Set your webhook URL in Platform Settings. All webhooks must use HTTPS.
No User Content in Webhooks
DeepaData webhooks never include user message content, transcripts, or personally identifiable information. Payloads contain only computed signals, metadata, and identifiers.
This design ensures that your webhook receiver can be deployed without special PII handling requirements for the webhook payloads themselves.
Event Types
DeepaData currently fires webhooks for two event types.
safety.evaluation
Fires when a Safety evaluation returns advisory, flag, or critical outcome. Never fires on pass outcomes.
observe.escalation
Fires when an Observe observation has escalate_recommended: true or trigger is risk_signal.
safety.evaluation Payload
Sent when a Safety evaluation detects a concern worth escalating.
{
"event": "safety.evaluation",
"timestamp": "2026-02-27T14:30:00.000Z",
"data": {
"artifact_id": "esaa-01JMXYZ...",
"platform_id": "my-companion-app",
"session_id": "session-12345",
"evaluation_outcome": "flag",
"safety_score": 0.45,
"manipulation_signature": 0.72,
"primary_trigger": "vulnerability_exploitation",
"recommended_action": "escalate_to_human",
"escalate_recommended": true
}
}| Field | Type | Description |
|---|---|---|
| artifact_id | string | Unique identifier for the ESAA artifact |
| platform_id | string | Your platform identifier from the evaluation request |
| session_id | string | null | Session identifier if provided in the request |
| evaluation_outcome | string | One of: advisory, flag, critical |
| safety_score | number | Safety score (0.0 to 1.0, higher = safer) |
| manipulation_signature | number | Weighted composite of manipulation signals (0.0 to 1.0) |
| primary_trigger | string | Main safety concern detected (e.g., vulnerability_exploitation) |
| recommended_action | string | Suggested response: log_and_monitor, escalate_to_human, etc. |
| escalate_recommended | boolean | True if outcome is flag or critical |
observe.escalation Payload
Sent when an Observe observation detects a risk signal or recommends escalation.
{
"event": "observe.escalation",
"timestamp": "2026-02-27T14:30:00.000Z",
"data": {
"passage_hash": "a1b2c3d4e5f6...",
"subject_id": "user-123",
"session_id": "session-456",
"observation_date": "2026-02-27T14:30:00.000Z",
"trigger": "risk_signal",
"escalate_recommended": true,
"state_change": "Disclosure of self-harm ideation detected",
"significance": 0.95,
"affect_intensity": 0.85,
"affect_valence": "negative",
"priority": "critical",
"confidence": 0.92
}
}| Field | Type | Description |
|---|---|---|
| passage_hash | string | Hash of the observed content for deduplication |
| subject_id | string | Your subject identifier from the request |
| session_id | string | null | Session identifier if provided |
| observation_date | string | ISO 8601 timestamp of the observation |
| trigger | string | One of: risk_signal, recurrence, affect_shift, topic_shift, user_mark, session_close, time_gap |
| escalate_recommended | boolean | True if escalation is recommended |
| state_change | string | null | Human-readable description of what changed |
| significance | number | Significance score (0.0 to 1.0) |
| affect_intensity | number | Emotional intensity (0.0 to 1.0) |
| affect_valence | string | null | One of: positive, negative, mixed, null |
| priority | string | One of: low, medium, high, critical |
| confidence | number | Confidence in the observation (0.0 to 1.0) |
Request Headers
Every webhook request includes the following headers.
Content-Type
Always application/json
User-Agent
DeepaData-Webhook/1.0
X-DeepaData-Event
The event type (e.g., safety.evaluation or observe.escalation)
HMAC Signature Verification
Coming Soon
HMAC signature verification is on our roadmap. When available, each webhook request will include a X-DeepaData-Signature header containing an HMAC-SHA256 signature of the request body, allowing you to verify that the webhook originated from DeepaData.
Receiving Events
Your webhook endpoint should return a 2xx status code to acknowledge receipt. Failed deliveries are logged but not currently retried.
Testing tip: Use a service like webhook.site to inspect incoming payloads during development. Copy your unique URL and paste it into Platform Settings.
Example Receiver
A minimal Node.js/Express webhook receiver:
const express = require('express');
const app = express();
app.use(express.json());
app.post('/webhooks/deepadata', (req, res) => {
const { event, timestamp, data } = req.body;
console.log(`Received ${event} at ${timestamp}`);
if (event === 'safety.evaluation') {
if (data.evaluation_outcome === 'critical') {
// Trigger immediate alert
alertOncallTeam(data);
}
}
if (event === 'observe.escalation') {
if (data.priority === 'critical') {
// Route to clinical review queue
queueForReview(data);
}
}
res.status(200).send('OK');
});
app.listen(3000);Delivery Behavior
Timeout
Webhook requests timeout after 10 seconds. Ensure your endpoint responds quickly.
HTTPS Required
All webhook URLs must use HTTPS. HTTP URLs will be rejected when saving settings.
Retries
Failed webhook deliveries are currently not retried. Retry logic is planned for a future release.