Obtener detalles de aplicaciones mediante webhooks

Resumen

Hirevire no expone una API pública para obtener datos de aplicaciones. En su lugar, usa webhooks personalizados para recibir automáticamente cargas útiles completas de las aplicaciones cuando los candidatos envían sus respuestas o cambian entre etapas.

Esta guía te muestra cómo configurar webhooks, analizar las cargas útiles de las aplicaciones, incluidos los enlaces de video y audio, e integrarlas con herramientas de automatización como Make.com.

Por qué usar webhooks en lugar de una API

Hirevire envía los datos de la aplicación a tu endpoint en tiempo real cuando ocurren eventos. Esto elimina la necesidad de consultar actualizaciones y garantiza que tus flujos de trabajo reciban la información del candidato inmediatamente después del envío.

Los webhooks entregan detalles completos de la aplicación, incluidos:

• Información de contacto del solicitante y enlaces del currículum

• Enlaces directos a respuestas de video y audio

• Transcripciones generadas por IA en más de 90 idiomas

• Archivos cargados y respuestas de texto

• Cambios de etapa y metadatos

Configurar webhooks en Hirevire

Configura webhooks por oferta de trabajo para enviar los datos de la aplicación a tu endpoint.

Paso 1: Prepara tu endpoint

Tu endpoint del webhook debe aceptar solicitudes POST con cargas útiles JSON y devolver un código de estado 200. Hirevire reintenta automáticamente las entregas fallidas del webhook cuando tu endpoint no devuelve un código de estado 200.

Si usas Make.com, Zapier o herramientas similares, primero genera una URL de webhook desde su plataforma (se explica en la sección de Make.com más abajo).

Paso 2: Añade la URL del webhook a tu trabajo

1. Ve a Jobs y selecciona el trabajo que quieres monitorear

2. Haz clic en la pestaña Settings

3. Abre la sección Webhook

4. Pega la URL de tu endpoint (por ejemplo, https://api.example.com/webhooks/applications)

Paso 3: Elige los disparadores

Selecciona cuándo Hirevire debe enviar datos a tu endpoint:

• On new application: Envía la carga útil cuando un candidato completa y envía su evaluación

• On stage change: Envía la carga útil cuando mueves manualmente a un candidato entre etapas después del envío

Puedes activar ambos disparadores al mismo tiempo.

Paso 4: Activa los datos avanzados del webhook

Activa "Include answers, video urls and transcripts" para recibir detalles completos de la solicitud, incluidos enlaces a medios y transcripciones de IA. Sin esta configuración, solo recibirás metadatos básicos del solicitante.

Paso 5: Prueba y guarda

Haz clic en Test trigger para enviar una carga útil de ejemplo a tu endpoint. Verifica que tu sistema reciba y procese los datos correctamente y luego haz clic en Save.

Supervisa el estado de entrega en la página de registros. Las entregas fallidas mostrarán detalles del error.

Entender los disparadores de webhook

Los webhooks solo se activan para solicitudes enviadas, no para la actividad del candidato antes del envío. Esto evita que datos duplicados o incompletos lleguen a tus integraciones.

Qué activa los webhooks

New submission event: Se activa cuando un candidato completa su evaluación y hace clic en enviar. La solicitud pasa del estado "In-progress" a "New" o "To be reviewed". La carga útil del webhook incluye todas las respuestas, las URLs de los medios y las transcripciones.

Stage change event: Se activa cuando mueves manualmente una solicitud entre etapas después del envío. Esto incluye pasar de "To be reviewed" a etapas personalizadas como "Interview" o "Rejected." La carga útil incluye la etapa anterior y la actual.

Qué NO activa los webhooks

Estos estados de candidato no activan webhooks:

• Invited: El candidato recibió una invitación, pero no ha शुरूado la solicitud. Consulta Bulk Invite candidates para ver cómo funciona esta etapa.

• In-progress: El candidato empezó a completar los detalles, pero no ha enviado todas las respuestas. Consulta Why do we have a lot of applications in "In-Progress" para más contexto.

Los webhooks solo se activan después de que un candidato envía su solicitud completa o cuando cambias la etapa de una solicitud enviada.

Ejemplos de cargas útiles de webhook

Aquí tienes ejemplos de cargas útiles para cada tipo de disparador, para ayudarte a crear integraciones.

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..."
    }
  ]
}

La diferencia clave: previousStage es null para nuevas solicitudes y tiene valor para cambios de etapa.

Entender las cargas útiles del webhook

Cuando se activa un webhook, Hirevire envía una solicitud POST con una carga útil JSON que contiene la aplicación completa.

Campos clave de la carga útil

Metadatos del solicitante:

• id: ID único de la aplicación

• applicantName, applicantEmail, applicantContactNumber: Datos de contacto

• applicantResumeURL: Enlace directo de descarga del currículum cargado

• shareableURL: Enlace para ver la solicitud completa en Hirevire

• submittedOn: Marca de tiempo ISO 8601

• currentStage / previousStage: Información de la etapa del flujo de trabajo

Array de respuestas: Cada objeto de respuesta contiene:

• question.text y question.responseType: Qué se preguntó y cómo

• url: Enlace directo al archivo de video o audio (formato MP4/WebM)

• transcript: Transcripción de texto generada por IA si está habilitada

• text: Contenido de la respuesta en texto

• fileURLs: Array de enlaces a archivos cargados

• numberOfRetakes: Cuántas veces volvió a grabar el candidato

Integrar con Make.com

Para una guía completa paso a paso sobre cómo conectar Hirevire a Make.com (anteriormente Integromat), consulta Connect Hirevire to Make.com.

Esta guía cubre la generación de tu clave de API, la creación de escenarios en Make, la configuración de webhooks y las pruebas de cargas útiles.

Descargar y almacenar archivos multimedia

Las URLs de video y audio en las cargas útiles del webhook son enlaces directos de descarga. Puedes obtener estos archivos de forma programática o manual.

Buenas prácticas para el manejo de medios

• Descarga inmediata: Los archivos multimedia expiran según el período de retención de tu plan (90 días en todos los planes). Descarga las grabaciones importantes a tu propio almacenamiento tan pronto como lleguen los webhooks.

• Almacenamiento seguro: Guarda los videos de los candidatos con los controles de acceso y el cifrado adecuados. Sigue las directrices del RGPD si procesas candidatos de la UE.

• Consideraciones de ancho de banda: Los archivos de video pueden ser grandes (5-50 MB por grabación). Usa tareas en segundo plano o colas para descargar archivos de forma asíncrona sin bloquear tu endpoint del webhook.

• Verificar descargas: Revisa los códigos de respuesta HTTP y el tamaño de los archivos para asegurarte de que las transferencias se completaron correctamente.

Para opciones de descarga manual y flujos de trabajo en el navegador, consulta Cómo descargar respuestas de video y audio de las aplicaciones.

Solución de problemas comunes

La carga útil del webhook no incluye URLs de video

Asegúrate de que el selector "Include answers, video urls and transcripts" esté activado en la configuración del webhook de tu trabajo. Los webhooks básicos solo envían metadatos del solicitante sin detalles de las respuestas.

El endpoint no recibe datos

Revisa lo siguiente:

• La URL de tu endpoint es accesible públicamente mediante HTTPS

• Tu servidor devuelve un código de estado 200 en las solicitudes POST

• Revisa la página de registros en Hirevire para ver mensajes de error

• Prueba tu endpoint con herramientas como Postman o curl usando la carga útil de ejemplo

Los videos caducaron o los enlaces devuelven 404

Los archivos multimedia se eliminan después del período de retención de tu plan. Actualiza a un plan con mayor retención o compra el complemento de extensión de almacenamiento ($9 por trabajo) para conservar los archivos 30 días adicionales más allá del límite de tu plan.

Los campos de transcripción están vacíos

Las transcripciones de IA están incluidas en todos los planes de pago. Si las transcripciones no aparecen, verifica que estén activadas en la configuración de preguntas de tu trabajo.

Webhook desactivado automáticamente tras varios fallos

Después de 5 entregas fallidas consecutivas, Hirevire desactiva automáticamente el webhook para proteger tu endpoint. Cuando esto ocurra, verás un banner en la configuración del webhook del trabajo que dirá:

Este webhook se desactivó automáticamente después de varios fallos

Si se muestra una marca de tiempo, incluirá la fecha y la hora en que se desactivó el webhook.

Hirevire también envía al propietario de la organización un correo electrónico con el asunto Hirevire: Webhook disabled for [Job Title] y el último error registrado.

Volver a activar un webhook desactivado:

1. Ve a Jobs y selecciona el trabajo afectado

2. Haz clic en la pestaña Settings

3. Abre la sección Webhook

4. Revisa el banner de estado desactivado y confirma que tu endpoint esté corregido

5. Haz clic en Re-enable

Hirevire vuelve a activar el webhook con una confirmación de Webhook re-enabled.

Reintentar una entrega fallida de webhook

Puedes reintentar entregas individuales de webhook fallidas desde los registros del panel:

1. Abre la página de registros del webhook

2. Filtra por Failed o Retrying

3. Selecciona las entregas que quieres reintentar

4. Elige la acción de reintento

También puedes filtrar los registros por Pending, Success o Failed para revisar el historial de entregas.

Verificar firmas de webhook

Cuando configuras un secreto de firma en el webhook de un trabajo, Hirevire firma cada entrega con HMAC-SHA256. Tu endpoint debe volver a calcular la firma a partir del cuerpo sin procesar y compararla con los encabezados de la solicitud antes de confiar en la carga útil.

Configurar un secreto de firma

La firma se configura por trabajo en la misma configuración de Webhook que la URL y los disparadores.

1. Abre Jobs, selecciona el trabajo y luego ve a Settings → Webhook.

2. En Signing secret, haz clic en Generate o pega tu propio secreto. Los secretos generados usan el prefijo whsec_ seguido de 48 caracteres hexadecimales.

3. Haz clic en Copy para guardar el secreto en tu receptor. Deja el campo en blanco para desactivar la firma.

4. Haz clic en Save.

Encabezados que envía Hirevire

Cuando se establece un secreto de firma, cada POST del webhook incluye estos encabezados:

El valor t en X-Hirevire-Signature coincide con X-Hirevire-Timestamp. El valor sha256 es el HMAC codificado en hexadecimal de la cadena firmada descrita abajo.

Cómo se construye la firma

Hirevire construye una cadena y luego la firma:

1. Toma la marca de tiempo Unix (segundos).

2. Añade un solo punto (.).

3. Añade el cuerpo JSON bruto exactamente como se envió (no reformatees ni vuelvas a serializar el JSON).

4. Calcula HMAC-SHA256 de esa cadena con tu secreto de firma y codifica el resultado en hexadecimal.

En resumen: cadena firmada = timestamp + "." + rawBody, luego hex(HMAC-SHA256(secret, signedString)).

Pasos de verificación en tu endpoint

1. Lee el cuerpo bruto de la solicitud como bytes o como cadena antes de cualquier análisis JSON que cambie los espacios en blanco o el orden de las claves.

2. Lee X-Hirevire-Timestamp.

3. Lee X-Hirevire-Signature y extrae el valor sha256= del formato t=...,sha256=....

4. Calcula HMAC-SHA256 sobre timestamp + "." + rawBody usando tu secreto de firma, como un hash hexadecimal.

5. Compara tu hash con el valor sha256 del encabezado. Acepta la solicitud solo cuando coincidan.

Ejemplo de verificación en 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");
});

Ejemplo de verificación en 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)

Seguridad y retención de datos

Las cargas útiles del webhook contienen información sensible de los candidatos. Sigue estas pautas:

• Usa endpoints HTTPS: Cifra los datos en tránsito para evitar su interceptación.

• Verifica las firmas: Configura un secreto de firma y valida X-Hirevire-Signature y X-Hirevire-Timestamp en cada solicitud usando los pasos de verificación anteriores.

• Limita la retención de datos: Guarda los videos y la información personal de los candidatos solo el tiempo necesario para tomar decisiones de contratación y luego elimínalos según los requisitos del RGPD y de privacidad.

• Controles de acceso: Restringe quién puede ver las grabaciones y transcripciones de candidatos en tus sistemas.

• Registros de auditoría: Registra quién accedió a los datos de la aplicación y cuándo.

Hirevire elimina automáticamente los datos de los candidatos cuando vence tu período de retención. Comunica tus prácticas de manejo de datos a los candidatos en tu oferta de empleo o política de privacidad.

Mejoras recientes de los webhooks

Hirevire mejoró recientemente la funcionalidad de los webhooks con una estructura de carga útil y opciones de configuración mejoradas. Revisa el registro de cambios de mejoras de webhooks personalizados para ver las últimas novedades.

Siguientes pasos

• Configura webhooks para tus trabajos activos

• Prueba las cargas útiles con tus herramientas de automatización

• Descarga a tu almacenamiento los videos importantes de candidatos

• Explora integraciones nativas como Ashby ATS para una integración más estrecha del flujo de trabajo