Webhook Integration Guide
Receive real-time updates about candidates, conversations and outcomes via HTTP POST callbacks.
Overview
TalentPrism sends each event as an HTTP POST with a JSON body to the endpoint you configure. Every body has the same
five top-level keys: event_id,
event_type,
created_at,
data and
metadata.
Use event_type to tell events apart; the shape of
data depends on it.
There are two kinds of event:
-
Activity events (
touchpoint.*,interview.*,call.call_completed,candidate.resume.added) report something that happened once: a reply arrived, an interview was completed, a call ended, a resume was read. -
Record events (
candidate.profile.upserted,conversation.summary.updated,recruiter_action.*,job_alert.*,referral.*,qualified_lead.*) send the current state of a saved record each time it changes, with arevisionnumber and achanged_fieldslist. See Reading record events.
Recent Changes
All changes are additive: no event was renamed and no existing field was removed or moved. Receivers should ignore fields and event types they do not recognise.
- September 25, 2026. People whose record is created by a text to our number now show
source_providerinbound_textandsource_mechanismchat. Before this, every text recordeddirect_application, including texts from people already on file; those earlier entries are not rewritten. Someone already on file who texts in keeps their source. - September 24, 2026. A candidate's source now means how their record first reached TalentPrism; see Where candidates come from. People whose record is created by a job's application page show
source_providerdirect_applicationandsource_mechanismapplication_pageincandidate.profile.upserted. Theirprovenanceentry names the job they applied to:origin_typeclient_jobwith your job id asorigin_id, andobtained_atis when they applied. People whose record is created when they identify themselves in the chat widget showchat_widgetandchat. People whose record is created from a talent pool search result showtalent_pool_searchandsearch. Someone already on file who applies, uses the chat widget or turns up in a search keeps their source; that is activity, not a new source. Texts to our number still recordeddirect_applicationon this date. Earlier records are not rewritten. Also new:candidate.resume.added, an event you can turn on in Team Settings. It fires once each time a resume is read and carries the full parsed resume and a link to the file. See Resume events. - September 16, 2026.
candidate.profile.upsertednow says where the candidate came from:source_provider(for examplepeoplegpt,factoryfix,ultrastaff; the full list ispeoplegpt,factoryfix,bullhorn,ultrastaff,linkedin,job_board,referral,direct_application(your application link),chat_widget(your chat widget),inbound_text(a text to our number),talent_pool_search(a talent pool search result),ats,other(the name is insource_provider_label) andunknown),source_provider_label,source_mechanism(for examplecsv_import,bulk_resume_upload),source_obtained_at,source_external_id(the provider's own id for the person), and the fullprovenancehistory. The source is saved just after the candidate, so it usually arrives as its own revision with these names inchanged_fields. - September 14, 2026.
metadata.client_metadata.company_nameis now always present, including on record events that are not tied to a campaign. - September 10, 2026.
interview.interview_completedfires as soon as a candidate finishes the interview. It no longer waits for the voice provider's own assessment, which was sometimes missing and caused finished interviews to be skipped. - September 8, 2026. Added all record events listed above, plus
call.call_completedfor phone calls not tied to an interview. Events are now chosen in Team Settings, grouped with a description of each, and can be sent without a campaign.
Setting Up Webhooks
- Open Team Settings → Default Webhook and enter your endpoint URL.
- Copy the signing secret. It is sent with every request (see Security).
- Pick the events you want, or use a preset: Recommended (test and completion events), Outcomes only, or Everything.
- Press Send test webhook to receive a
test.webhook_verificationevent.
A campaign can override the team endpoint and event list with its own. Campaigns without their own endpoint use the team settings.
Security
Every request includes an X-Talentprism-Signature header whose value is your webhook secret.
Compare it with the secret from Team Settings and reject requests that do not match.
Where candidates come from
Every candidate has a source: how their record first reached TalentPrism. It is sent as
source_provider and
source_mechanism, with the full history in
provenance, on
candidate.profile.upserted.
Everything a candidate does after that is activity, sent as its own events.
1. Source: set once, when the record is first created
Shown as path → source_provider / source_mechanism.
Candidate reached out first
-
Applied through your application link→ direct_application / application_page
-
Identified themselves in your chat widget, with no record before→ chat_widget / chat
-
Texted our number, with no record before→ inbound_text / chat
Added by a recruiter or an import
-
Shortlist CSV import→ the source chosen at upload / csv_import
-
Bulk resume upload→ the source chosen at upload / bulk_resume_upload
-
Talent pool search→ talent_pool_search / search
For example peoplegpt, factoryfix or ultrastaff. An upload states a
source, so importing someone already on file adds an entry for them too.
2. Activity: every later interaction, never changes the source
A candidate already on file who applies, chats or replies produces events like these. Their source stays as it was.
- Applies to another job interview.interview_opened, interview.interview_completed
- Replies to outreach touchpoint.responded, touchpoint.message_received
- Chats with the assistant conversation.summary.updated
- Sends a resume candidate.resume.added
- Is marked a qualified lead qualified_lead.created, qualified_lead.updated
Event Types
This list is generated from the same catalogue as the Team Settings picker. Events marked high volume can fire many times per candidate.
Outcomes
| Event | When it fires and what it carries |
|---|---|
| interview.interview_completed | Interview completed. A voice or web interview finished and was submitted. Carries the candidate, the interview id, its public link and completion status, plus when the interview was opened and exited. |
| call.call_completed | Call completed. A phone call that was not tied to an interview ended. Carries the call id, status, the AI summary, the caller's number, start and end times, and the candidate we matched the number to. |
| qualified_lead.created | Qualified lead created. A candidate first met every agreed criterion for a specific job. Carries the lead and job ids and the full assessment: criteria id and version, each criterion's met/not_met result and its evidence. |
| qualified_lead.updated | Qualified lead updated. An already-exported qualified lead changed, including losing its evidence — status then becomes no_longer_qualified with update_reason qualification_evidence_missing_or_invalid. |
| referral.created | Referral created. A candidate referred someone. Carries the referrer's candidate id, the referred person's name and contact, the job role and client job id. The referred person is not a candidate record here. |
| referral.updated | Referral updated. An already-exported referral's details changed, with the same payload plus changed_fields. |
Candidate records
| Event | When it fires and what it carries |
|---|---|
| candidate.profile.upserted | Candidate profile saved. A candidate record, its memory or its recorded source was saved. Carries the profile summary, normalized email, engagement summary, availability, do-not-contact and contact preference, plus where the candidate came from: the coarse source label, the latest provider, provider label, mechanism, obtained date and provider-side id, and the full provenance history. Has a revision number. |
| conversation.summary.updated | Conversation summary updated. A public chat went idle and its summary was re-synthesised. Carries the summary text, message count, channel and timestamps, plus the ids of any recruiter actions, referrals and qualified leads it produced. |
| candidate.resume.added | Resume added. A resume was parsed onto a candidate, whichever way it arrived: bulk or API upload, chat, text message, email attachment, the application page or a recruiter upload. Fires once per parsed resume and carries the full parsed resume (work history, education, skills and so on), a link to the file, its name and type, and how it arrived. (high volume) |
Recruiter actions
| Event | When it fires and what it carries |
|---|---|
| recruiter_action.created | Recruiter action created. The AI raised something for a human to handle. Carries the action type, subject, what is needed, priority, assignee, due date and source chat, and whether a human is still required. |
| recruiter_action.updated | Recruiter action updated. An open recruiter action changed — reassigned, re-prioritised, dismissed or deduped — with changed_fields listing what moved. |
| recruiter_action.completed | Recruiter action completed. A recruiter action moved to completed. Carries completed_at, the completion source and closed reason. Email or digest delivery alone does not fire this — only actual human completion does. |
Job alerts
| Event | When it fires and what it carries |
|---|---|
| job_alert.created | Job alert created. A candidate asked to be told about future openings. Carries the alert id, the role, location and rate they asked for, and their preferred channel. |
| job_alert.updated | Job alert updated. An active job alert's role, location, rate or channel changed, with changed_fields. |
| job_alert.cancelled | Job alert cancelled. A job alert was deactivated; status is cancelled and no further alerts should be expected. |
Interview progress
| Event | When it fires and what it carries |
|---|---|
| interview.interview_consent_selection | Consent given. A candidate made a consent choice on the interview page. Carries the selection, the method and path it came through, and when it was given. |
| interview.resume_uploaded | Resume uploaded. A candidate uploaded a resume during an interview. Carries the upload time and the file URL. |
| interview.interview_opened | Interview opened. A candidate opened their interview page. Fires on every open, before any answer exists, so it is noisy relative to its value. (high volume) |
Message delivery
| Event | When it fires and what it carries |
|---|---|
| touchpoint.message_received | Inbound message received. Every inbound SMS or email reply, first and follow-ups. Carries the message text, the outreach message it answers, the channel and the AI analysis of the reply. (high volume) |
| touchpoint.responded | First reply received. The first time a candidate replies to a given outreach message. Same payload as inbound message received; use this one if you only want to know that a conversation started. (high volume) |
| touchpoint.failed | Delivery failed. The provider could not send the message. Carries the failure reason and marks the phone or email invalid on the candidate's contact record. |
| touchpoint.undelivered | Message bounced. The message was sent but bounced or was never delivered. Carries the bounce reason and the resulting recipient status. |
| touchpoint.unsubscribed | Unsubscribed. A candidate replied STOP or unsubscribed from an email. Carries when it happened; the candidate is suppressed from further outreach on that channel. |
| touchpoint.rejected | Message rejected. The email provider rejected the message outright. Carries the rejection reason and marks the address invalid. |
Testing
| Event | When it fires and what it carries |
|---|---|
| test.webhook_verification | Test webhook. Sent only when someone presses Send test webhook. Carries a fixed sample payload so a receiver can verify its URL and signature check without waiting for real activity. |
Reading Record Events
Record events send the whole current record every time, not just the part that changed. The record sits under a key
named after it: data.profile for
candidate.profile.upserted, and
data.recruiter_action,
data.job_alert,
data.referral or
data.qualified_lead for the others.
conversation.summary.updated uses
data.conversation and
data.outcomes.
| Field | Meaning |
|---|---|
| <record>.revision | Counts the versions sent for this record, starting at 1. Apply a delivery only if its revision is higher than the one you already hold. |
| data.changed_fields | Names of the fields in the record that differ from the previous revision. Missing on revision 1, because everything is new. A save that changes nothing is not sent at all. |
| data.classification | category is informational or recruiter_action. Only open recruiter actions have action_required: true; everything else is for your records. |
| data.api_refs | Stable ids (candidate, chat, action and so on) for looking the record up through the TalentPrism API. |
| data.candidate | The same candidate block as activity events. It is null on referral events: the referrer is in referral.referrer and the referred person is not a candidate record yet. |
| data.export_context.mode | live_snapshot when sent as the change happened; current_state_reconciliation when a background check re-sent a change that had not been delivered. Both describe the record's current state. |
For example, if the candidate's availability changes in a chat, you receive a new
candidate.profile.upserted with the next revision and
"changed_fields": ["availability_status"].
If you only care about some changes, check changed_fields before processing.
Record events contain short summaries only. They never include full transcripts or recordings; use the ids in api_refs to fetch details. For resumes, turn on candidate.resume.added, which sends the parsed resume and a file link once per resume (see Resume events).
Example: candidate.profile.upserted
All people, companies, identifiers, URLs, and timestamps in this example are synthetic.
{
"event_id": "evt_00000000000040008000000000000002",
"event_type": "candidate.profile.upserted",
"created_at": "2026-03-14T20:31:03Z",
"data": {
"candidate": {
"candidate_id": 12345,
"screenname": "John Smith",
"first_name": "John",
"last_name": "Smith",
"email": "john.smith@example.com",
"phone": null
},
"profile": {
"summary": "CNC machinist with five years of 5-axis experience.",
"normalized_email": "john.smith@example.com",
"engagement_summary": "Replied to outreach; open to contract roles.",
"availability_status": "actively_looking",
"do_not_contact": false,
"contact_preference": "sms",
"source": null,
"source_provider": "peoplegpt",
"source_provider_label": null,
"source_mechanism": "csv_import",
"source_obtained_at": "2026-03-10T00:00:00Z",
"source_external_id": "EXT-1001",
"provenance": [
{
"provider": "peoplegpt",
"provider_display": "PeopleGPT",
"mechanism": "csv_import",
"mechanism_display": "CSV import",
"external_id": "EXT-1001",
"obtained_at": "2026-03-10T00:00:00Z",
"imported_at": "2026-03-12T15:00:00Z"
}
],
"created_at": "2026-03-12T15:00:00Z",
"updated_at": "2026-03-14T20:31:00Z",
"revision": 3
},
"changed_fields": ["engagement_summary", "availability_status"],
"classification": {"category": "informational", "action_required": false, "priority": "normal"},
"api_refs": {"candidate_id": 12345},
"export_context": {"mode": "live_snapshot"}
},
"metadata": {
"account": "Example Staffing Co",
"job_title": null,
"client_metadata": {"company_name": "Example Staffing Co"},
"version": "1.0"
}
}
Resume Events
candidate.resume.added is off until you turn it on.
It fires once each time a resume is read onto a candidate, however it arrived: bulk or API upload, chat, text
message, email, the application page or a recruiter upload. A candidate who sends a new resume later gets a new
event. It is not a record event, so it has no revision;
deduplicate on resume.resume_parse_request_id or
event_id.
resume.file_urlis a direct link to the file, ornullif no file was kept.resume.ingest_sourcesays how the resume arrived, for examplebulk,api,sms_mmsorsequence_interview(the application or interview page).resume.parsed_resumeis the full parsed resume. Its fields depend on what the resume contained; ignore any you do not use.- Bulk imports send one event per resume, so a large upload sends many events close together.
Example: candidate.resume.added
All people, companies, identifiers, URLs, and timestamps in this example are synthetic.
{
"event_id": "evt_00000000000040008000000000000003",
"event_type": "candidate.resume.added",
"created_at": "2026-03-14T20:35:10Z",
"data": {
"candidate": {
"candidate_id": 12345,
"screenname": "John Smith",
"first_name": "John",
"last_name": "Smith",
"email": "john.smith@example.com",
"phone": null
},
"resume": {
"resume_parse_request_id": 67890,
"file_url": "https://files.example.com/resume/john-smith.pdf",
"file_name": "john-smith.pdf",
"content_type": "application/pdf",
"ingest_source": "sequence_interview",
"parsed_at": "2026-03-14T20:35:09Z",
"parsed_resume": {
"full_name": "John Smith",
"candidate_email": "john.smith@example.com",
"role": "CNC Machinist",
"summary": "CNC machinist with five years of 5-axis experience.",
"skills": ["5-axis milling", "GD&T", "Blueprint reading"],
"work_experience": [
{"company": "Example Machining LLC", "title": "CNC Machinist", "start_date": "2021-01", "end_date": null}
],
"education": [{"institution": "Example Technical College", "degree": "Machining Certificate"}]
}
},
"api_refs": {"candidate_id": 12345}
},
"metadata": {
"account": "Example Staffing Co",
"job_title": null,
"client_metadata": {"company_name": "Example Staffing Co"},
"version": "1.0"
}
}
Delivery and Retries
- Respond with any 2xx status within 10 seconds to acknowledge an event.
- Failed deliveries are retried up to 5 attempts in total, with growing gaps of up to 5 minutes. A retry sends the same body with the same
event_id. - An event can occasionally arrive twice (for example after a network timeout). Deduplicate on
event_id. - Events can arrive out of order. For record events, keep the highest
revisionyou have seen for each record and ignore older ones.
How client_metadata Is Resolved
metadata.client_metadata carries your own identifiers. Interview events add one extra rule so the job id stays tied to the correct application.
- Base payload uses the campaign's client metadata, when the event belongs to a campaign.
- Candidate metadata may add extra keys for the same candidate (for example the id you supplied on import).
company_namefalls back to your team name when nothing else sets it.- For interview events,
client_job_idis resolved from the current interview before any candidate-level fallback is used. - Internal application history is not emitted in the webhook payload.
Example: interview.interview_completed
All people, companies, identifiers, URLs, and timestamps in this example are synthetic.
{
"event_id": "evt_00000000000040008000000000000001",
"event_type": "interview.interview_completed",
"created_at": "2026-03-14T20:31:03Z",
"data": {
"channel": "webCall",
"candidate": {
"candidate_id": 12345,
"screenname": "John Smith",
"first_name": "John",
"last_name": "Smith",
"email": "john.smith@example.com",
"phone": null
},
"interview": {
"interview_id": "00000000-0000-4000-8000-000000000001",
"candidate_id": 12345,
"status": "completed",
"public_url": "https://talentprism.ai/candidate/interview/example-token/"
},
"response": {
"interview_opened_at": "2026-03-14T20:30:00Z",
"interview_exited_at": "2026-03-14T20:31:00Z"
}
},
"metadata": {
"account": "Example Staffing Co",
"job_title": "Welder Application Intake",
"client_metadata": {
"company_name": "Example Staffing Co",
"client_job_id": "JOB-12345",
"jobs_list_url": "https://example.com/jobs.json",
"jobs_page_url": "https://example.com/jobs",
"job_page_url_format": "https://example.com/jobs/{job_id}",
"referral_fee": "$200",
"referral_hours_requirement": "160 hours"
},
"version": "1.0"
}
}
Activity Event Schema
data.channel is
"email" or
"sms" for messages, and
"inboundPhoneCall",
"outboundPhoneCall" or
"webCall" for calls and interviews.
Activity event payload
├── event_id (string, unique per event; retries reuse it)
├── event_type (string)
├── created_at (string - ISO 8601 datetime)
├── data
│ ├── channel (string)
│ ├── candidate (object | null)
│ │ ├── candidate_id (integer)
│ │ ├── screenname, first_name, last_name (string)
│ │ ├── email (string | null)
│ │ └── phone (string | null)
│ │
│ ├── touchpoint (touchpoint.* events)
│ │ ├── touchpoint_id, candidate_id, outreach_message_id
│ │ ├── channel ("email" | "sms")
│ │ └── status (string)
│ ├── MsgTitle, MsgBody, MsgStatus (touchpoint.* events - the outreach message)
│ │
│ ├── interview (interview.* events)
│ │ ├── interview_id (string), candidate_id (integer)
│ │ ├── status (string)
│ │ └── public_url (string | null)
│ │
│ ├── call (call.call_completed)
│ │ ├── id, status, summary, caller_phone_number
│ │ └── call_started_at, call_ended_at (ISO 8601 | null)
│ │
│ └── response (touchpoint.* and interview.* events; varies by event_type)
│ ├── touchpoint.responded: responded_at, content, ai_analysis
│ ├── touchpoint.message_received: message_received_at, content, ai_analysis
│ ├── touchpoint.failed / undelivered / rejected: reason and recipient status
│ └── interview.interview_completed: interview_opened_at, interview_exited_at
│
└── metadata
├── account (string - your team name)
├── job_title (string | null - the campaign title)
├── client_metadata (object - see "How client_metadata Is Resolved")
└── version ("1.0")
Can't find what you're looking for?
Contact Us