Documentation Index
Fetch the complete documentation index at: https://docs.talview.com/llms.txt
Use this file to discover all available pages before exploring further.
Understanding these concepts will help you correctly interpret webhook payloads and build reliable integrations.
Event Naming Convention
Every webhook event follows a consistent naming pattern:
| Format | Example |
|---|
| Subscription Key (dot-separated) | can.candidate.created |
| Event Type (underscore-separated) | can_candidate_created |
created, updated, or deleted.
Payload Visibility Rules
All webhook payloads follow two strict visibility rules:
| Excluded Field | Reason |
|---|
tenant_id | Implicit from your subscription context. Your webhook subscription is scoped to your tenant, so this field is redundant. |
is_deleted | Internal soft-delete flag. Instead of seeing is_deleted: true, you will receive a deleted event. Subordinate arrays in payloads are pre-filtered to exclude soft-deleted records. |
If you previously relied on tenant_id in payloads, note that it is no longer included. Your subscription already scopes events to your tenant.
Subordinate Bubble-Up
Talview webhooks operate on root-level objects only. When a nested (subordinate) record changes, the system does not fire a separate event for the subordinate. Instead, the parent root object’s updated_at is touched in the same database transaction, which fires an updated event on the root with the full current payload.
Example
Adding an education record to a candidate does not produce a can.education.created event. Instead, it triggers a can.candidate.updated event containing the candidate’s complete profile, including the new education entry in the education array.
Why this design?
- Simplicity: Consumers subscribe to a small set of root events instead of tracking dozens of subordinate tables.
- Consistency: Every
updated payload is a complete snapshot of the root object — no need to merge partial updates.
- Atomicity: The subordinate change and the root’s
updated_at touch happen in the same transaction, preventing ordering issues.
Versioned-Snapshot Objects
Most root objects have a dedicated history table (e.g., sch.meeting_history, pay.transaction_status_history) that records prior states. For these objects, updated event payloads contain only the current state.
However, some objects have no history table. These are called versioned-snapshot objects, and their updated payloads include both the previous and current state:
{
"old": { /* previous state */ },
"new": { /* current state */ }
}
Objects with versioned-snapshot behavior
| Root Object | Reason |
|---|
frm.form_instance | No form_instance_history table exists. The old key provides the complete previous row so consumers can compute diffs. |
Check each event’s documentation page to see whether old state is included in updated payloads.
Cross-Service Payloads
Some root objects aggregate data from multiple services to provide full context in a single payload. This means the webhook delivers a rich, denormalized view — no additional API calls needed.
| Root Object | Services Joined | What’s Included |
|---|
coordinator.exam | coordinator, workflow-tools, scheduler, pm | Workflow steps, drive schedules, rooms, and proctoring center details. |
pm.center | pm, workflow-tools, scheduler, geo-location | Workflow steps, drive schedules with rooms and seats, operating schedule with availabilities and overrides, geographic location. |
ae.test_instance | assessment-engine, candidate, evaluation | Candidate snapshot, catalog/assessment metadata, measurement scores and attributes. |
pay.transaction | payment, order | Full order chain including order items, SKUs, and applied coupons. |
sch.meeting | scheduler, auth | Participant list with user identity snapshots from the auth service. |
incident.instance | incident, session | Session snapshot with status and score from the session service. |
