Overview

General behavior, reliability, and transport mechanics of the Webhook system.

What are Webhooks?

Webhooks are automated messages sent from one system to another when a specific event occurs. Think of them as “push notifications” for your servers. Instead of your system constantly asking (polling) the Talview API if there are new updates, Talview pushes that data to your system the moment it happens.

This approach is significantly more efficient, reduces API load, and ensures your integration reacts to platform events — like a candidate finishing an exam — in real-time.

---

Talview Webhooks

Talview uses webhooks to notify your system about critical lifecycle events across assessments, interviews, forms, payments, and more.

Before diving into individual events, review the Webhook Concepts page for important behavioral rules such as payload visibility, subordinate bubble-up, and versioned snapshots.

Available Webhook Events

The following table lists all events that are currently available for subscription, grouped by service:

Service	Event ID	Trigger Description	Common Use Case
Assessment Engine	ae_test_instance_created	A candidate starts a new assessment attempt.	Logging the start time in an external LMS.
	ae_test_instance_updated	A test attempt is updated (e.g., score calculated, status changes).	Automatically retrieving results once a test is completed.
Auth	auth_user_created	A new user is created in the Talview system.	Syncing user accounts with your internal HRIS.
	auth_user_updated	An existing user’s profile or role assignments change.	Keeping user details consistent across systems.
Candidate	can_candidate_created	A new candidate profile is created.	Syncing candidate records to your ATS.
	can_candidate_updated	A candidate’s profile or subordinate records change.	Keeping candidate data in sync with external systems.
Coordinator	coordinator_exam_created	A new exam is created in the coordinator.	Setting up corresponding records in an external proctoring system.
	coordinator_exam_updated	An exam’s configuration, workflow, or center assignment changes.	Syncing exam changes to external scheduling systems.
Form	form_form_instance_created	A new form submission is received.	Capturing feedback or registration data.
	form_form_instance_updated	A form submission is updated.	Tracking form revision history.
Incident	incident_instance_created	A new proctoring incident is detected.	Triggering immediate intervention alerts.
	incident_instance_updated	A proctoring incident is updated or resolved.	Compliance logging and incident tracking.
Payment	pay_transaction_created	A new payment transaction is initiated.	Tracking pending revenue or booking attempts.
	pay_transaction_updated	A payment status changes (e.g., Success, Failed, Refunded).	Confirming a candidate’s slot after successful payment.
Proctoring Management	pm_center_created	A new proctoring center is created.	Provisioning center resources in an external system.
	pm_center_updated	A proctoring center’s configuration or schedule changes.	Syncing center availability with external calendars.
Scheduler	sch_meeting_created	A new interview or meeting is scheduled.	Adding the event to an external calendar or ATS.
	sch_meeting_updated	A meeting is rescheduled, cancelled, or its status changes.	Sending updated meeting links to participants.

Planned Events

The following root objects have been identified for future webhook support but are not yet available for subscription:

Service	Root Object	Description
Auth	auth.tenant	Tenant configuration changes.
Auth	app.instance	App installation and permission changes.
Candidate Auth	ca.profile	Candidate authentication profile.
Evaluation	tcf.measurement	Evaluation measurements.
Event	event.event	Platform events.
Form	frm.form	Form definition changes.
Help Center	hc.page	Help center page updates.
Message	message.channel	Chat channel changes.
Notify	notify.message	Notification messages.
Payment	pay.sku	SKU (product) definition changes.
Project	pc.project	Project management updates.
Scheduler	sch.drive_schedule	Drive schedule management.
Session	session.instance	Session lifecycle events.
Sync	sync.config	Sync configuration changes.
Taxonomy	tax.skill	Skill taxonomy updates.
VoIP	voip.call_history	Call history records.
VR	vr.room	Virtual room changes.
Workflow Tools	wft.workflow	Workflow definition changes.
Workflow Tools	wft.job	Job requisition changes.
Workflow Tools	wft.workflow_candidate	Candidate pipeline progression.
Endpoint Protection	ep.policy	Security policy changes.

These events are under development. Contact your Talview representative for timeline information.

---

Technical Implementation

HTTP Request Pattern

All webhooks are delivered using a standard HTTP request pattern:

POST <your_configured_url> HTTP/1.1
Host: <your_server_host>
Content-Type: application/json

{
  ...payload
}

• Method: Defaults to POST (configurable to PUT or PATCH during registration).
• Body: The raw JSON payload of the event. There is no outer “envelope” or wrapper.

Verifying Webhook Signatures

Every delivery is signed with HMAC-SHA256 so your endpoint can confirm a request genuinely came from Talview and the body wasn’t altered in transit.

Two headers are added to every request, on top of any custom headers configured on the subscription:

Header	Description
X-Hook-Timestamp	Unix timestamp (seconds) at which the delivery was signed.
X-Hook-Signature	sha256=<hex-encoded HMAC-SHA256 digest> of the timestamp and body.

Custom headers set on a subscription’s target (hook.target.headers) are merged in first, then Content-Type, X-Hook-Timestamp, and X-Hook-Signature are applied on top — a custom header can never override the security headers or the request body encoding.

Secret

Each subscription target has its own signing secret — secrets are per-target, not per-application. You receive the secret in the target.secret field of the hook_subscribe response. It’s returned every time you call hook_subscribe for that target, including on a repeat/idempotent subscription, so you can always re-fetch it by re-subscribing. Only TENANT_ADMIN and PLATFORM_ADMIN callers can see it.

To rotate a secret, update the target with the update_hook_target mutation.

Computing the Signature

signature = hex(HMAC-SHA256(secret, "{timestamp}.{raw_body}"))

• timestamp is the exact value sent in X-Hook-Timestamp.
• raw_body is the exact request body as transmitted — sign the literal bytes you received, not a re-serialized version of the parsed JSON, since key ordering or whitespace differences will produce a different digest.

Verification Example (Node.js)

const crypto = require('crypto');

function isValidSignature({ secret, timestamp, rawBody, signatureHeader }) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');
  const provided = signatureHeader.replace('sha256=', '');

  // Reject stale deliveries to guard against replay attacks.
  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
  if (age > 300) return false;

  return crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(provided, 'hex'));
}

Always use a constant-time comparison (like crypto.timingSafeEqual) rather than === when comparing signatures, to avoid leaking timing information.

Signature verification is a recommendation, not an enforced requirement — endpoints that don’t check it keep receiving deliveries unaffected. Talview’s outbound HTTPS client currently does not verify your endpoint’s TLS certificate.