What are webhooks?

Webhooks let TalentSprout send real-time HTTP POST requests to your server when specific events happen. This is useful for integrating with your own systems, triggering automations, or syncing data to tools that TalentSprout doesn't natively integrate with.

Supported events

TalentSprout supports two webhook events:

interview.completed — Fired when a candidate finishes an AI interview and the evaluation is generated.
interview.abandoned — Fired when a candidate starts but does not complete the interview and the session expires.

Configuring your webhook URL

To set up a webhook for all interviews:

Go to Settings in the left sidebar.
Scroll to the Global Interview Settings section.
Find the Webhook URL field and click Edit.
The field has a fixed https:// prefix — all webhook URLs must use HTTPS. Enter the rest of your URL (e.g., example.com/webhook).
Click Save changes.

All completed and abandoned interviews will now trigger a POST request to this URL.

Interview-level override

You can also set a webhook URL on individual interviews to override the global setting:

Open the interview and go to the Settings tab.
Find the Webhook URL section.
Enter a URL and click Save changes.

Leave the field empty to use the global webhook URL from your organization settings.

💡

Tip: Use the interview-level override when you need different webhooks for different roles or integrations.

Webhook payload

The webhook POST request includes a JSON body with detailed candidate and interview data:

Event metadata — Event type (interview.completed or interview.abandoned), API version, and timestamp.
Interview — Interview ID, title, company name, and a dashboard URL.
Candidate — First name, last name, full name, email, phone, external user ID, profile URL, and share URL.
Session — Session ID, token, type, status, start/end timestamps, duration, recording URL, thumbnail URL, and resume URL.
Validation — Whether the candidate passed validation, the reason, and when it was checked.
Scores — Overall score, interview score, and resume score.
Integrity — Integrity score, risk level, and any flags detected.
Evaluation — Performance summary, five category scores, language proficiency scores (if applicable), AI-generated summary with strengths and concerns, and custom scores (if configured).
Resume evaluation — Overall resume score, sub-criteria scores, and resume highlights (if resume screening is enabled).
Transcript — Full interview transcript with timestamps.

Webhook signing and verification

Webhook signing lets you verify that requests came from TalentSprout and were not tampered with. This follows Stripe's webhook signing pattern for familiarity and security.

Enabling webhook authentication:

Go to Settings > Global Interview Settings.
Find the Webhook Authentication section and turn it on.
A modal displays your signing secret (prefixed with whsec_). Copy it immediately — you won't be able to see it again.

⚠️

Important: Copy your signing secret immediately when it's displayed. You won't be able to see it again. If you lose it, you'll need to regenerate a new one.

How signing works:

Each outgoing webhook includes an X-TalentSprout-Signature header.
The header value has the format: t={timestamp},v1={signature}.
The signature is an HMAC SHA-256 hash of the string {timestamp}.{raw_body}, using your webhook secret as the key.

Verifying the signature on your server:

Parse the X-TalentSprout-Signature header to extract t (timestamp) and v1 (signature).
Read the raw request body (before parsing JSON).
Construct the signed payload string: {t}.{body}.
Compute an HMAC SHA-256 hash of that string using your webhook secret.
Compare your computed hash to the v1 value. If they match, the request is authentic.

Example verification (Node.js):

const crypto = require('crypto');function verifyWebhook(body, signatureHeader, secret) {
  const parts = Object.fromEntries(
    signatureHeader.split(',').map(p => p.split('='))
  );
  const timestamp = parts.t;
  const expectedSig = parts.v1;  const signedPayload = `${timestamp}.${body}`;
  const computedSig = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');  return computedSig === expectedSig;
}

Managing your webhook secret

Your webhook secret is stored securely and displayed as a masked value (whsec_••••••••). To regenerate it:

Go to Settings > Global Interview Settings > Webhook Authentication.
Click the regenerate icon next to the masked secret.
Confirm by clicking Regenerate secret in the dialog.
Copy the new secret from the modal — it is only shown once.

⚠️

Note: After regenerating, update the secret in your server immediately to avoid rejecting valid webhooks.

Testing webhooks

Click Send Test next to the webhook URL field to send a sample payload to your endpoint. This lets you verify your server is receiving and processing webhooks correctly before going live.

Troubleshooting

HTTPS required — Webhook URLs must use HTTPS. HTTP URLs are not supported.
30-second timeout — TalentSprout waits up to 30 seconds for your server to respond. If the request times out, it is not retried.
Check response codes — A successful webhook delivery expects a 2xx HTTP response. Non-2xx responses are logged as failures.
Verify the URL is accessible — Ensure your endpoint is publicly reachable and not blocked by firewalls or authentication.

Setting Up Webhooks