Fetch application details via webhooks

Overview

Hirevire does not expose a public API for fetching application data. Instead, use custom webhooks to receive full application payloads automatically when candidates submit responses or move between stages.

This guide shows you how to configure webhooks, parse application payloads including video and audio URLs, and integrate with automation tools like Make.com.

Why webhooks instead of an API

Hirevire pushes application data to your endpoint in real-time when events occur. This eliminates the need to poll for updates and ensures your workflows receive candidate information immediately after submission.

Webhooks deliver complete application details including:

• Applicant contact information and resume links

• Direct video and audio response URLs

• AI-generated transcripts in 90+ languages

• File uploads and text answers

• Stage changes and metadata

Configure webhooks in Hirevire

Set up webhooks on a per-job basis to send application data to your endpoint.

Step 1: Prepare your endpoint

Your webhook endpoint must accept POST requests with JSON payloads. Hirevire retries failed webhook deliveries automatically when a delivery fails — see Webhook logs and delivery retries for the retry schedule and which failures are retried.

If you're using Make.com, Zapier, or similar tools, generate a webhook URL from their platform first (covered in the Make.com section below).

Step 2: Add webhook URL to your job

1. Navigate to Jobs and select the job you want to monitor

2. Click the Settings tab

3. Open the Webhook section

4. Paste your endpoint URL (e.g., https://api.example.com/webhooks/applications)

Step 3: Choose triggers

Select when Hirevire should send data to your endpoint:

• On new application: Sends payload when a candidate completes and submits their screening

• On stage change: Sends payload when you manually move a candidate between stages after submission

You can enable both triggers simultaneously.

Step 4: Enable advanced webhook data

Toggle "Include answers, video urls and transcripts" to receive full application details including media links and AI transcripts. Without this setting, you'll only receive basic applicant metadata.

Step 5: Test and save

Click Test trigger to send a sample payload to your endpoint. Verify your system receives and processes the data correctly, then click Save.

Monitor delivery status on the logs page. Failed deliveries will show error details.

Understanding webhook triggers

Webhooks fire only for submitted applications, not pre-submission candidate activity. This prevents duplicate or incomplete data from reaching your integrations.

What triggers webhooks

New submission event: Fires when a candidate completes their screening and clicks submit. The application moves from "In-progress" to "New" or "To be reviewed" status. The webhook payload includes all answers, media URLs, and transcripts.

Stage change event: Fires when you manually move an application between stages after submission. This includes moving from "To be reviewed" to custom stages like "Interview" or "Rejected." The payload includes both the previous and current stage.

What does NOT trigger webhooks

These candidate states do not fire webhooks:

• Invited: Candidate received an invitation but has not started the application. See Bulk Invite candidates for how this stage works.

• In-progress: Candidate started filling in details but has not submitted all answers. See Why do we have a lot of applications in "In-Progress" for context.

Webhooks only fire after a candidate submits their complete application or you change the stage of a submitted application.

Sample webhook payloads

Here are example payloads for each trigger type to help you build integrations.

New submission payload:

{
  "id": 12345,
  "jobID": 789,
  "jobTitle": "Senior Developer",
  "applicantName": "John Doe",
  "applicantEmail": "[email protected]",
  "applicantContactNumber": "+1234567890",
  "customFieldValue": "Referral code ABC",
  "applicantResumeURL": "https://storage.hirevire.com/resumes/resume.pdf",
  "shareableURL": "https://app.hirevire.com/shared/links/abc123",
  "submittedOn": "2025-01-15T10:30:00Z",
  "previousStage": null,
  "currentStage": "New",
  "answers": [
    {
      "question": {
        "id": "q_123",
        "text": "Tell us about yourself",
        "responseType": "Video"
      },
      "id": 456,
      "url": "https://storage.hirevire.com/videos/candidate-response.mp4",
      "transcript": "I have 5 years of experience in full-stack development...",
      "numberOfRetakes": 2
    },
    {
      "question": {
        "id": "q_124",
        "text": "Why do you want this role?",
        "responseType": "Text"
      },
      "id": 457,
      "text": "I'm passionate about building scalable applications..."
    }
  ]
}

Stage change payload:

{
  "id": 12345,
  "jobID": 789,
  "jobTitle": "Senior Developer",
  "applicantName": "John Doe",
  "applicantEmail": "[email protected]",
  "applicantContactNumber": "+1234567890",
  "customFieldValue": "Referral code ABC",
  "applicantResumeURL": "https://storage.hirevire.com/resumes/resume.pdf",
  "shareableURL": "https://app.hirevire.com/shared/links/abc123",
  "submittedOn": "2025-01-15T10:30:00Z",
  "previousStage": "New",
  "currentStage": "Interview",
  "answers": [
    {
      "question": {
        "id": "q_123",
        "text": "Tell us about yourself",
        "responseType": "Video"
      },
      "id": 456,
      "url": "https://storage.hirevire.com/videos/candidate-response.mp4",
      "transcript": "I have 5 years of experience in full-stack development...",
      "numberOfRetakes": 2
    },
    {
      "question": {
        "id": "q_124",
        "text": "Why do you want this role?",
        "responseType": "Text"
      },
      "id": 457,
      "text": "I'm passionate about building scalable applications..."
    }
  ]
}

The key difference: previousStage is null for new submissions and populated for stage changes.

Understanding webhook payloads

When a webhook triggers, Hirevire sends a POST request with a JSON payload containing the complete application.

Key payload fields

Applicant metadata:

• id: Unique application ID

• applicantFirstName, applicantLastName, and applicantName: Applicant name details

• applicantEmail: Contact email

• applicantContactNumber: Contact phone number, nullable

• applicantWhatsappNumber, applicantLinkedInProfile, applicantGithubProfile: WhatsApp, LinkedIn, and GitHub contact details, only when the candidate provides them

• applicantDateOfAvailability and applicantDateOfBirth: Availability date and date of birth, only when these are collected

• customFieldValue: Answer to a custom field, only when a custom field is enabled

• applicantResumeURL: Direct download link to the uploaded resume, only when resumes are enabled

• ipAddress: Candidate IP address, only when captured

• location: Object with city, region, and country, only when captured

• shareableURL: Link to view the full application in Hirevire

• submittedOn: ISO 8601 timestamp

• currentStage: Current workflow stage

• previousStage: Previous workflow stage, only for stage-change deliveries

• ashbyMetadata: Object with Ashby metadata, only when the application came from Ashby

Fields marked as optional in the sample payload appear only when the corresponding data is collected or available. previousStage is included only when a webhook fires for a stage change, not for new submissions.

Answers array: Each answer object contains:

• question.text and question.responseType: What was asked and how

• url: Direct link to video or audio file (MP4/WebM format)

• transcript: AI-generated text transcript if enabled

• text: Text answer content

• fileURLs: Array of uploaded file links

• numberOfRetakes: How many times the candidate re-recorded

Integrate with Make.com

For a complete step-by-step guide to connecting Hirevire to Make.com (formerly Integromat), see Connect Hirevire to Make.com.

This guide covers generating your API key, creating Make scenarios, configuring webhooks, and testing payloads.

Download and store media files

Video and audio URLs in webhook payloads are direct download links. You can fetch these files programmatically or manually.

Best practices for media handling

• Download immediately: Media files expire based on your plan's retention period (90 days on all plans). Download critical recordings to your own storage as soon as webhooks arrive.

• Secure storage: Store candidate videos with appropriate access controls and encryption. Follow GDPR guidelines if processing EU applicants.

• Bandwidth considerations: Video files can be large (5-50 MB per recording). Use background jobs or queues to download files asynchronously without blocking your webhook endpoint.

• Verify downloads: Check HTTP response codes and file sizes to ensure successful transfers.

For manual download options and browser-based workflows, see How to download video and audio responses from applications.

Troubleshooting common issues

Webhook payload missing video URLs

Ensure the "Include answers, video urls and transcripts" toggle is enabled in your job's webhook settings. Basic webhooks only send applicant metadata without answer details.

Endpoint not receiving data

Check the following:

• Your endpoint URL is publicly accessible via HTTPS

• Your server responds to POST requests within the 30-second timeout

• Review the logs page in Hirevire for error messages

• Test your endpoint with tools like Postman or curl using the sample payload

Videos expired or links return 404

Media files are deleted after your plan's retention period. Upgrade to a longer retention plan or purchase the storage extension add-on ($9 per job) to keep files for 30 additional days beyond your plan limit.

Transcript fields are empty

AI transcripts are included on all paid plans. If transcripts aren't appearing, verify that transcripts are enabled in your job's question settings.

Webhook auto-disabled after repeated failures

After 5 consecutive failed deliveries, Hirevire automatically disables the webhook to protect your endpoint. When this happens, you will see a banner in the job's webhook settings that says:

This webhook was auto-disabled after repeated failures

If a timestamp is shown, it will include the date and time the webhook was disabled.

Hirevire also sends the organisation owner an email with the subject Hirevire: Webhook disabled for [Job Title] and the last recorded error.

Re-enable a disabled webhook:

1. Navigate to Jobs and select the affected job

2. Click the Settings tab

3. Open the Webhook section

4. Review the disabled status banner and confirm your endpoint is fixed

5. Click Re-enable

Hirevire re-enables the webhook with a Webhook re-enabled. confirmation.

Retry a failed webhook delivery

You can retry individual failed webhook deliveries from the dashboard logs:

1. Open the webhook logs page

2. Filter by Failed or Retrying

3. Select the deliveries you want to retry

4. Choose the retry action

You can also filter the logs by Pending, Success, or Failed to review delivery history.

Verify webhook signatures

When you set a signing secret on a job webhook, Hirevire signs each delivery with HMAC-SHA256. Your endpoint should recompute the signature from the raw body and compare it to the request headers before trusting the payload.

Set a signing secret

Signing is configured per job in the same Webhook settings as the URL and triggers.

1. Open Jobs, select the job, then go to Settings → Webhook.

2. In Signing secret, click Generate or paste your own secret. Generated secrets use the whsec_ prefix followed by 48 hex characters.

3. Click Copy to store the secret in your receiver. Leave the field blank to disable signing.

4. Click Save.

Headers Hirevire sends

When a signing secret is set, every webhook POST includes these headers:

The t value in X-Hirevire-Signature matches X-Hirevire-Timestamp. The sha256 value is the hex-encoded HMAC of the signed string described below.

How the signature is built

Hirevire builds one string, then signs it:

1. Take the Unix timestamp (seconds).

2. Append a single period (.).

3. Append the raw JSON request body exactly as sent (do not reformat or re-serialize the JSON).

4. Compute HMAC-SHA256 of that string with your signing secret and encode the digest as hex.

In short: signed string = timestamp + "." + rawBody, then hex(HMAC-SHA256(secret, signedString)).

Verification steps on your endpoint

1. Read the raw request body as bytes or a string before any JSON parsing that would change whitespace or key order.

2. Read X-Hirevire-Timestamp.

3. Read X-Hirevire-Signature and parse the sha256= value from the t=...,sha256=... format.

4. Compute HMAC-SHA256 over timestamp + "." + rawBody using your signing secret, as a hex digest.

5. Compare your digest to the sha256 value from the header. Accept the request only when they match.

Example verification in Node.js:

const crypto = require("crypto");

function verifyHirevireSignature({ rawBody, timestampHeader, signatureHeader, secret }) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestampHeader}.${rawBody}`)
    .digest("hex");

  // signatureHeader format: t=<timestamp>,sha256=<hex>
  const match = /sha256=([a-f0-9]+)/i.exec(signatureHeader || "");
  const provided = match ? match[1] : "";

  if (!provided || provided.length !== expected.length) {
    return false;
  }

  return crypto.timingSafeEqual(
    Buffer.from(provided, "utf8"),
    Buffer.from(expected, "utf8")
  );
}

// Express-style handler: use the raw body string, not JSON.stringify(req.body)
app.post("/webhooks/hirevire", express.raw({ type: "application/json" }), (req, res) => {
  const rawBody = req.body.toString("utf8");
  const ok = verifyHirevireSignature({
    rawBody,
    timestampHeader: req.get("X-Hirevire-Timestamp"),
    signatureHeader: req.get("X-Hirevire-Signature"),
    secret: process.env.HIREVIRE_WEBHOOK_SECRET,
  });

  if (!ok) {
    return res.status(401).send("Invalid signature");
  }

  const payload = JSON.parse(rawBody);
  // process payload
  res.status(200).send("ok");
});

Example verification in Python:

import hmac
import hashlib
import re

def verify_hirevire_signature(raw_body: bytes | str, timestamp: str, signature_header: str, secret: str) -> bool:
    if isinstance(raw_body, bytes):
        raw_body = raw_body.decode("utf-8")

    expected = hmac.new(
        secret.encode("utf-8"),
        f"{timestamp}.{raw_body}".encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()

    match = re.search(r"sha256=([a-f0-9]+)", signature_header or "", re.I)
    provided = match.group(1) if match else ""

    return hmac.compare_digest(provided, expected)

Security and data retention

Webhook payloads contain sensitive candidate information. Follow these guidelines:

• Use HTTPS endpoints: Encrypt data in transit to prevent interception.

• Verify signatures: Set a signing secret and validate X-Hirevire-Signature and X-Hirevire-Timestamp on every request using the verification steps above.

• Limit data retention: Store candidate videos and personal information only as long as needed for hiring decisions, then delete per GDPR/privacy requirements.

• Access controls: Restrict who can view candidate recordings and transcripts in your systems.

• Audit logs: Track who accessed application data and when.

Hirevire automatically deletes candidate data after your retention period expires. Communicate your data handling practices to candidates in your job posting or privacy policy.

Recent webhook improvements

Hirevire recently enhanced webhook functionality with improved payload structure and configuration options. Review the custom webhook improvements changelog for the latest updates.

Next steps

• Set up webhooks for your active jobs

• Test payloads with your automation tools

• Download critical candidate videos to your storage

• Explore native integrations like Ashby ATS for tighter workflow integration