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.

With the answers switch enabled, webhook payloads include:

• Applicant contact information and resume links

• Direct video and audio response URLs

• AI-generated transcripts in 90+ languages

• File uploads and text answers

• Reference answers as structured data

With the switch off, the payload still contains the full application metadata, but the answers array is empty.

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 deliveries automatically; see Webhook logs and delivery retries for the full 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 under Custom Webhook Integration

4. Paste your endpoint URL into Custom webhook 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 a payload when a candidate completes and submits their screening

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

You can enable both triggers simultaneously.

Step 4: Enable advanced webhook data

Open Advanced Settings and turn on Include answers, video urls and transcripts to receive full application details including media links and AI transcripts. Without this setting, the payload contains basic applicant metadata and an empty answers array.

Step 5: Test and save

Click Test trigger to send a sample payload to your endpoint. The test respects the answers switch: with it off, the sample payload has an empty answers array. Verify your system receives and processes the data correctly, then click Save.

Monitor delivery status on the logs page. Failed deliveries 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. With answers enabled, the 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.

Understanding webhook payloads

When a webhook triggers, Hirevire sends a POST request with a JSON payload containing the 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

Answers array: Every answer object always contains:

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

• id: The answer ID

• transcript: AI-generated transcript text, or an empty string when no transcript exists

• numberOfRetakes: How many times the candidate re-recorded

The additional fields depend on the question's responseType:

References answers

When a question uses the References response type, the answer's value field is an array of reference objects. Each object contains:

• firstName and lastName: The reference's name

• email, phone, company, and relationship: Contact details, company, and relationship, when provided

• relationshipDetail: Extra relationship detail, present when the candidate selected Other as the relationship

Supported relationship values are Supervisor, Co-worker, Mentor, Client, and Other. References answers are included only when Include answers, video urls and transcripts is enabled on the job webhook. See How to collect references in a job post for setting up the questions.

Sample webhook payloads

Example payload for a new submission:

{
  "id": 12345,
  "jobID": 789,
  "jobTitle": "Senior Developer",
  "applicantName": "John Doe",
  "applicantEmail": "[email protected]",
  "applicantContactNumber": "+1234567890",
  "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..."
    }
  ]
}

For a stage-change delivery, the payload is the same shape but previousStage holds the stage the application moved from, for example "previousStage": "New" with "currentStage": "Interview". previousStage is null for new submissions.

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. That 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 (see below). 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.

• Download asynchronously: Use background jobs or queues to download files 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.

Video retention periods

Recordings are kept for 30 days on the One Job and Startup plans, and for 90 days on the Growth plan. You can extend video storage from the Billing tab of your profile under Extend Video Storage Duration, in multiples of 30 days. The extension applies only to videos recorded after the purchase.

Troubleshooting common issues

Webhook payload missing video URLs

Ensure the Include answers, video urls and transcripts switch is enabled under Advanced Settings in your job's webhook settings. Without it, payloads contain applicant metadata and an empty answers array.

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

• Use Test trigger in the job's webhook settings to send a sample payload

Videos expired or links return 404

Recordings are deleted after your plan's retention period: 30 days on One Job and Startup, 90 days on Growth. Purchase additional storage from the Billing tab of your profile to keep new recordings longer.

Transcript fields are empty

Transcripts are included in the transcript field of each answer when transcripts are enabled for the question in your job's settings. If transcript fields arrive empty, check that the question has transcripts enabled.

Webhook auto-disabled after repeated failures

After 5 consecutive terminal delivery failures, Hirevire automatically disables the webhook to protect your endpoint. A delivery that is still retrying does not count toward this limit. 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 includes the date and time the webhook was disabled. Hirevire also sends the organisation owner an email containing the job, the endpoint, 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

Each delivery gets up to three attempts: the initial attempt, a retry after 1 minute, and a retry after 10 minutes. Transport failures, timeouts, HTTP 429 responses, and HTTP 500 or higher responses are retried; other failed statuses are terminal on the first attempt.

You can also retry individual failed deliveries from the dashboard logs. For the full retry schedule, log filters, and re-enable behavior, see Webhook logs and delivery retries.

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 deletes recorded media after your plan's retention period expires. Communicate your data handling practices to candidates in your job posting or privacy policy.

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