← Help Center

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 a revision number and a changed_fields list. 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_provider inbound_text and source_mechanism chat. Before this, every text recorded direct_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_provider direct_application and source_mechanism application_page in candidate.profile.upserted. Their provenance entry names the job they applied to: origin_type client_job with your job id as origin_id, and obtained_at is when they applied. People whose record is created when they identify themselves in the chat widget show chat_widget and chat. People whose record is created from a talent pool search result show talent_pool_search and search. 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 recorded direct_application on 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.upserted now says where the candidate came from: source_provider (for example peoplegpt, factoryfix, ultrastaff; the full list is peoplegpt, 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 in source_provider_label) and unknown), source_provider_label, source_mechanism (for example csv_import, bulk_resume_upload), source_obtained_at, source_external_id (the provider's own id for the person), and the full provenance history. The source is saved just after the candidate, so it usually arrives as its own revision with these names in changed_fields.
  • September 14, 2026. metadata.client_metadata.company_name is now always present, including on record events that are not tied to a campaign.
  • September 10, 2026. interview.interview_completed fires 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_completed for 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

  1. Open Team Settings → Default Webhook and enter your endpoint URL.
  2. Copy the signing secret. It is sent with every request (see Security).
  3. Pick the events you want, or use a preset: Recommended (test and completion events), Outcomes only, or Everything.
  4. Press Send test webhook to receive a test.webhook_verification event.

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>.revisionCounts 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_fieldsNames 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.classificationcategory is informational or recruiter_action. Only open recruiter actions have action_required: true; everything else is for your records.
data.api_refsStable ids (candidate, chat, action and so on) for looking the record up through the TalentPrism API.
data.candidateThe 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.modelive_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_url is a direct link to the file, or null if no file was kept.
  • resume.ingest_source says how the resume arrived, for example bulk, api, sms_mms or sequence_interview (the application or interview page).
  • resume.parsed_resume is 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 revision you 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.

  1. Base payload uses the campaign's client metadata, when the event belongs to a campaign.
  2. Candidate metadata may add extra keys for the same candidate (for example the id you supplied on import).
  3. company_name falls back to your team name when nothing else sets it.
  4. For interview events, client_job_id is resolved from the current interview before any candidate-level fallback is used.
  5. 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