Obtener detalles de las solicitudes mediante webhooks

Descripción general

Hirevire no ofrece una API pública para obtener datos de solicitudes. En su lugar, usa webhooks personalizados para recibir automáticamente cargas completas de las solicitudes cuando los candidatos envían respuestas o pasan de una etapa a otra.

Esta guía te muestra cómo configurar webhooks, analizar cargas de solicitudes, incluidas las URL de vídeos y audios, e integrarlos con herramientas de automatización como Make.com.

Por qué usar webhooks en lugar de una API

Hirevire envía los datos de las solicitudes a tu endpoint en tiempo real cuando se producen eventos. Esto elimina la necesidad de consultar periódicamente las actualizaciones y garantiza que tus flujos de trabajo reciban la información de los candidatos inmediatamente después del envío.

Los webhooks proporcionan detalles completos de las solicitudes, incluidos:

• Información de contacto del candidato y enlaces a su currículum

• URL directas de las respuestas de vídeo y audio

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

• Archivos subidos y respuestas de texto

• Cambios de etapa y metadatos

Configurar webhooks en Hirevire

Configura los webhooks por oferta de empleo para enviar los datos de las solicitudes a tu endpoint.

Paso 1: Prepara tu endpoint

Tu endpoint de webhook debe aceptar solicitudes POST con cargas JSON. Hirevire vuelve a intentar automáticamente las entregas de webhook fallidas cuando una entrega no se completa correctamente; consulta Registros de webhooks y reintentos de entrega para conocer el calendario de reintentos y qué errores se vuelven a intentar.

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

Paso 2: Añade la URL del webhook a tu oferta de empleo

1. Ve a Ofertas de empleo y selecciona la oferta que quieres supervisar

2. Haz clic en la pestaña Configuración

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 activadores

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

• Al recibir una nueva solicitud: Envía la carga cuando un candidato completa y envía su evaluación

• Al cambiar de etapa: Envía la carga cuando mueves manualmente a un candidato entre etapas después del envío

Puedes activar ambos activadores simultáneamente.

Paso 4: Activa los datos avanzados del webhook

Activa "Incluir respuestas, URL de vídeos y transcripciones" para recibir todos los detalles de la solicitud, incluidos los enlaces a archivos multimedia y las transcripciones de IA. Sin esta opción, solo recibirás los metadatos básicos del candidato.

Paso 5: Prueba y guarda

Haz clic en Probar activador para enviar una carga de ejemplo a tu endpoint. Verifica que tu sistema recibe y procesa los datos correctamente y, después, haz clic en Guardar.

Supervisa el estado de las entregas en la página de registros. Las entregas fallidas mostrarán información sobre el error.

Cómo funcionan los activadores de webhook

Los webhooks solo se activan para solicitudes enviadas, no para la actividad de los candidatos anterior al envío. Esto evita que lleguen datos duplicados o incompletos a tus integraciones.

Qué activa los webhooks

Evento de nueva solicitud: Se activa cuando un candidato completa su evaluación y hace clic en enviar. La solicitud pasa del estado "En curso" a "Nueva" o "Pendiente de revisión". La carga del webhook incluye todas las respuestas, las URL de archivos multimedia y las transcripciones.

Evento de cambio de etapa: Se activa cuando mueves manualmente una solicitud entre etapas después del envío. Esto incluye moverla de "Pendiente de revisión" a etapas personalizadas como "Entrevista" o "Rechazada". La carga incluye la etapa anterior y la actual.

Qué NO activa los webhooks

Estos estados de los candidatos no activan webhooks:

• Invitado: El candidato ha recibido una invitación, pero no ha iniciado la solicitud. Consulta Invitar candidatos en bloque para saber cómo funciona esta etapa.

• En curso: El candidato ha empezado a completar sus datos, pero todavía no ha enviado todas las respuestas. Consulta Por qué tenemos muchas solicitudes "En curso" para obtener más contexto.

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

Ejemplos de cargas de webhook

Aquí tienes cargas de ejemplo para cada tipo de activador que te ayudarán a crear integraciones.

Carga de nueva solicitud:

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

Carga de cambio de etapa:

{
  "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 en las nuevas solicitudes y contiene un valor en los cambios de etapa.

Cómo funcionan las cargas de webhook

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

Campos principales de la carga

Metadatos del candidato:

• id: ID único de la solicitud

• applicantFirstName, applicantLastName y applicantName: Datos del nombre del candidato

• applicantEmail: Correo electrónico de contacto

• applicantContactNumber: Número de teléfono de contacto, puede ser nulo

• applicantWhatsappNumber, applicantLinkedInProfile, applicantGithubProfile: Datos de contacto de WhatsApp, LinkedIn y GitHub, solo cuando el candidato los proporciona

• applicantDateOfAvailability y applicantDateOfBirth: Fecha de disponibilidad y fecha de nacimiento, solo cuando se recopilan estos datos

• customFieldValue: Respuesta a un campo personalizado, solo cuando hay un campo personalizado habilitado

• applicantResumeURL: Enlace de descarga directa al currículum subido, solo cuando los currículums están habilitados

• ipAddress: Dirección IP del candidato, solo cuando se captura

• location: Objeto con city, region y country, solo cuando se captura

• shareableURL: Enlace para ver la solicitud completa en Hirevire

• submittedOn: Marca de tiempo ISO 8601

• currentStage: Etapa actual del flujo de trabajo

• previousStage: Etapa anterior del flujo de trabajo, solo para entregas por cambio de etapa

• ashbyMetadata: Objeto con metadatos de Ashby, solo cuando la solicitud procede de Ashby

Los campos marcados como opcionales en la carga de ejemplo solo aparecen cuando se recopilan o están disponibles los datos correspondientes. previousStage solo se incluye cuando un webhook se activa por un cambio de etapa, no en las nuevas solicitudes.

Matriz de respuestas: Cada objeto de respuesta contiene:

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

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

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

• text: Contenido de la respuesta de texto

• fileURLs: Matriz de enlaces a archivos subidos

• numberOfRetakes: Número de veces que el candidato volvió a grabar la respuesta

Integrar con Make.com

Para consultar una guía completa paso a paso sobre cómo conectar Hirevire con Make.com (antes Integromat), consulta Conectar Hirevire con Make.com.

Esta guía explica cómo generar tu clave de API, crear escenarios de Make, configurar webhooks y probar cargas.

Descargar y almacenar archivos multimedia

Las URL de vídeos y audios incluidas en las cargas de webhook son enlaces de descarga directa. Puedes obtener estos archivos mediante programación o manualmente.

Prácticas recomendadas para gestionar archivos multimedia

• Descarga inmediata: Los archivos multimedia caducan según el periodo de conservación de tu plan (90 días en todos los planes). Descarga las grabaciones importantes en tu propio almacenamiento en cuanto lleguen los webhooks.

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

• Consideraciones sobre el ancho de banda: Los archivos de vídeo pueden ser grandes (entre 5 y 50 MB por grabación). Usa trabajos en segundo plano o colas para descargar los archivos de forma asíncrona sin bloquear tu endpoint de webhook.

• Verifica las descargas: Comprueba los códigos de respuesta HTTP y el tamaño de los archivos para asegurarte de que las transferencias se han completado correctamente.

Para consultar opciones de descarga manual y flujos de trabajo basados en el navegador, consulta Cómo descargar respuestas de vídeo y audio de las solicitudes.

Solución de problemas habituales

A la carga del webhook le faltan las URL de los vídeos

Asegúrate de que la opción "Incluir respuestas, URL de vídeos y transcripciones" esté activada en la configuración del webhook de tu oferta de empleo. Los webhooks básicos solo envían los metadatos del candidato, sin detalles de las respuestas.

El endpoint no recibe datos

Comprueba lo siguiente:

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

• Tu servidor responde a las solicitudes POST dentro del tiempo de espera de 30 segundos

• Consulta la página de registros de Hirevire para ver los mensajes de error

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

Los vídeos han caducado o los enlaces devuelven un error 404

Los archivos multimedia se eliminan una vez transcurrido el periodo de conservación de tu plan. Cambia a un plan con un periodo de conservación más largo o compra el complemento de ampliación de almacenamiento (9 $ por oferta) para conservar los archivos durante 30 días adicionales al 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 no aparecen las transcripciones, comprueba que estén habilitadas en la configuración de preguntas de tu oferta de empleo.

El webhook se desactivó automáticamente tras varios errores

Después de 5 entregas fallidas consecutivas, Hirevire desactiva automáticamente el webhook para proteger tu endpoint. Cuando esto ocurre, verás un aviso en la configuración del webhook de la oferta de empleo que dice:

Este webhook se desactivó automáticamente tras varios errores

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 Ofertas de empleo y selecciona la oferta afectada

2. Haz clic en la pestaña Configuración

3. Abre la sección Webhook

4. Revisa el aviso de estado desactivado y confirma que tu endpoint está corregido

5. Haz clic en Volver a activar

Hirevire vuelve a activar el webhook y muestra la confirmación Webhook re-enabled.

Reintentar una entrega de webhook fallida

Puedes volver a intentar entregas de webhook fallidas individuales desde los registros del panel:

1. Abre la página de registros del webhook

2. Filtra por Fallido o Reintentando

3. Selecciona las entregas que quieres volver a intentar

4. Elige la acción de reintento

También puedes filtrar los registros por Pendiente, Correcto o Fallido para revisar el historial de entregas.

Verificar las firmas de los webhooks

Cuando estableces un secreto de firma en el webhook de una oferta de empleo, Hirevire firma cada entrega con HMAC-SHA256. Tu endpoint debe volver a calcular la firma a partir del cuerpo sin procesar y compararla con las cabeceras de la solicitud antes de confiar en la carga.

Establecer un secreto de firma

La firma se configura por oferta de empleo, en la misma configuración de Webhook que la URL y los activadores.

1. Abre Ofertas de empleo, selecciona la oferta y ve a Configuración → Webhook.

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

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

4. Haz clic en Guardar.

Cabeceras que envía Hirevire

Cuando se establece un secreto de firma, cada POST del webhook incluye estas cabeceras:

El valor t de X-Hirevire-Signature coincide con X-Hirevire-Timestamp. El valor sha256 es el HMAC codificado en hexadecimal de la cadena firmada que se describe a continuación.

Cómo se crea la firma

Hirevire crea una cadena y, después, la firma:

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

2. Añade un único punto (.).

3. Añade el cuerpo de la solicitud JSON sin procesar exactamente como se envió (no reformatees ni vuelvas a serializar el JSON).

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

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

Pasos de verificación en tu endpoint

1. Lee el cuerpo sin procesar de la solicitud como bytes o como una cadena antes de realizar cualquier análisis JSON que pueda cambiar los espacios en blanco o el orden de las claves.

2. Lee X-Hirevire-Timestamp.

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

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

5. Compara tu resumen con el valor sha256 de la cabecera. 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 conservación de datos

Las cargas de webhook contienen información confidencial de los candidatos. Sigue estas directrices:

• Usa endpoints HTTPS: Cifra los datos durante la transmisión para evitar su interceptación.

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

• Limita la conservación de datos: Almacena los vídeos y la información personal de los candidatos solo durante el tiempo necesario para tomar decisiones de contratación y, después, elimínalos de acuerdo con los requisitos del RGPD y de privacidad.

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

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

Hirevire elimina automáticamente los datos de los candidatos cuando vence el periodo de conservación. Informa a los candidatos sobre tus prácticas de gestión de datos en la oferta de empleo o en la política de privacidad.

Mejoras recientes de los webhooks

Hirevire ha mejorado recientemente la funcionalidad de los webhooks con una estructura de cargas y opciones de configuración mejoradas. Consulta el registro de cambios de las mejoras de los webhooks personalizados para conocer las últimas actualizaciones.

Próximos pasos

• Configura webhooks para tus ofertas de empleo activas

• Prueba las cargas con tus herramientas de automatización

• Descarga los vídeos importantes de los candidatos en tu almacenamiento

• Explora integraciones nativas como Ashby ATS para integrar mejor los flujos de trabajo