Obtener detalles de 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 útiles completas de las solicitudes cuando los candidatos envían sus respuestas o pasan de una etapa a otra.

Esta guía explica cómo configurar webhooks, analizar las cargas útiles de las solicitudes, incluidas las URL de video y audio, 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. Así, no es necesario consultar si hay actualizaciones y tus flujos de trabajo reciben la información de los candidatos inmediatamente después del envío. La excepción es la opción Incluir tarjeta de puntuación de IA: cuando está activada, los envíos de nuevas solicitudes esperan a que termine la puntuación de IA antes de enviarse.

Con el interruptor de respuestas activado, las cargas útiles de los webhooks incluyen:

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

• URL directas de las respuestas en video y audio

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

• Archivos subidos y respuestas de texto

• Respuestas a preguntas de referencia como datos estructurados

Con el interruptor desactivado, la carga útil sigue incluyendo todos los metadatos de la solicitud, pero el arreglo answers está vacío.

Configurar webhooks en Hirevire

Configura webhooks para cada puesto 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 útiles JSON. Hirevire vuelve a intentar automáticamente las entregas fallidas; consulta Registros de webhooks y reintentos de entrega para ver el calendario completo de reintentos y qué fallos se vuelven a intentar.

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

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

1. Ve a Puestos y selecciona el puesto que quieres supervisar

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

3. Abre la sección Webhook en Integración con webhook personalizado

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

Paso 3: Elige los activadores

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

• Al enviar una nueva solicitud: envía una carga útil cuando un candidato completa y envía su evaluación de selección

• Al cambiar de etapa: envía una carga útil cuando mueves manualmente a un candidato de una etapa a otra después del envío

Puedes activar ambos activadores al mismo tiempo.

Paso 4: Activa los datos avanzados del webhook

Abre Configuración avanzada y activa Incluir respuestas, URL de videos 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, la carga útil incluye los metadatos básicos del solicitante y un arreglo answers vacío.

Paso 5: Prueba y guarda

Haz clic en Probar activador para enviar una carga útil de muestra a tu endpoint. La prueba respeta el interruptor de respuestas: si está desactivado, la carga útil de muestra tiene un arreglo answers vacío. Comprueba que tu sistema reciba y procese los datos correctamente y, luego, haz clic en Guardar.

Supervisa el estado de las entregas en la página de registros. Las entregas fallidas muestran los detalles del error.

Cómo funcionan los activadores de webhooks

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

Qué activa los webhooks

Evento de nuevo envío: se activa cuando un candidato completa su evaluación de selección y hace clic en Enviar. La solicitud pasa del estado «En curso» a «Nueva» o «Pendiente de revisión». Si las respuestas están activadas, la carga útil incluye todas las respuestas, las URL de archivos multimedia y las transcripciones.

Evento de cambio de etapa: se activa cuando mueves manualmente una solicitud de una etapa a otra después de su envío. Esto incluye pasar de «Pendiente de revisión» a etapas personalizadas como «Entrevista» o «Rechazado». La carga útil incluye la etapa anterior y la actual.

Qué NO activa los webhooks

Estos estados de los candidatos no activan webhooks:

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

• En curso: el candidato empezó a completar sus datos, pero todavía no ha enviado todas sus 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.

Cómo entender las cargas útiles de los webhooks

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

Campos principales de la carga útil

Metadatos del solicitante:

• id: ID único de la solicitud

• applicantFirstName, applicantLastName y applicantName: datos del nombre del solicitante

• applicantEmail: correo electrónico de contacto

• applicantContactNumber: teléfono de contacto; puede ser nulo

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

• applicantDateOfAvailability y applicantDateOfBirth: fecha de disponibilidad y fecha de nacimiento, solo si se recopilan

• customFieldValue: respuesta a un campo personalizado, solo si se activa un campo personalizado

• applicantResumeURL: enlace de descarga directa al currículum subido, solo si los currículums están activados

• ipAddress: dirección IP del candidato, solo si se captura

• location: objeto con city, region y country, solo si 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 si la solicitud proviene de Ashby

Arreglo de respuestas: cada objeto de respuesta siempre contiene:

• question.id, question.text y question.responseType: qué se preguntó y de qué manera

• id: ID de la respuesta

• transcript: texto de la transcripción generada por IA, o una cadena vacía si no hay ninguna transcripción

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

Los campos adicionales dependen del responseType de la pregunta:

Respuestas de referencia

Cuando una pregunta usa el tipo de respuesta References, el campo value de la respuesta es un arreglo de objetos de referencia. Cada objeto contiene:

• firstName y lastName: nombre de la referencia

• email, phone, company y relationship: datos de contacto, empresa y relación, si se proporcionaron

• relationshipDetail: información adicional sobre la relación, presente si el candidato seleccionó Otro como relación

Los valores admitidos para relationship son Supervisor, Co-worker, Mentor, Client y Other. Las respuestas de referencia solo se incluyen si Incluir respuestas, URL de videos y transcripciones está activado en el webhook del puesto. Consulta Cómo recopilar referencias en una publicación de empleo para configurar las preguntas.

Datos de la tarjeta de puntuación de IA

Activa Incluir tarjeta de puntuación de IA en la configuración de Webhook de un puesto para añadir un objeto scorecard de nivel superior a las cargas útiles de nuevas solicitudes y cambios de etapa. El interruptor aparece justo debajo de Incluir respuestas, URL de videos y transcripciones y solo se puede activar en un puesto que tenga una tarjeta de puntuación.

El objeto scorecard contiene:

• status: Completed, Pending o Failed

• error: el motivo por el que no se ejecutó la puntuación; solo cuando status es Failed; de lo contrario, null

• score: la puntuación total ponderada sobre 5, con dos decimales

• maxScore: 5

• scoredOn: marca de tiempo ISO 8601 de la ejecución de puntuación, o null si la solicitud aún no se ha puntuado

• factors: una entrada por cada factor de la tarjeta de puntuación, cada una con name, weightage (porcentaje), score (sobre 5) y reasons. Cada motivo tiene un type de Positive o Negative y una explicación en text.

El momento de entrega varía según el activador. Los webhooks de nuevas solicitudes se retienen hasta que termina la puntuación, por lo que la carga útil llega con la puntuación final. Si la puntuación sigue en curso después de 30 minutos, Hirevire entrega la carga útil con status establecido en Pending y no envía ningún evento de seguimiento. Los webhooks de cambio de etapa no se retienen mientras se espera la puntuación: la carga útil incluye la tarjeta de puntuación tal como está cuando se genera el evento, por lo que puede llegar mientras el webhook de nueva solicitud del mismo candidato todavía espera a que termine la puntuación.

Ejemplos de cargas útiles de webhook

Ejemplo de carga útil para un nuevo envío:

{
  "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",
  "scorecard": {
    "status": "Completed",
    "error": null,
    "score": 3.8,
    "maxScore": 5,
    "scoredOn": "2025-01-15T10:30:00Z",
    "factors": [
      {
        "name": "Communication",
        "weightage": 40,
        "score": 4,
        "reasons": [
          { "type": "Positive", "text": "Clear, structured answer with relevant examples" }
        ]
      }
    ]
  },
  "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..."
    }
  ]
}

El objeto scorecard se incluye si Incluir tarjeta de puntuación de IA está activado para el puesto.

En una entrega por cambio de etapa, la carga útil tiene la misma estructura, pero previousStage contiene la etapa desde la que pasó la solicitud; por ejemplo, "previousStage": "New" con "currentStage": "Interview". previousStage es null en los nuevos envíos.

Integrar con Make.com

Para ver una guía completa paso a paso para conectar Hirevire con Make.com (antes Integromat), consulta Conectar Hirevire con Make.com. La guía explica cómo generar tu clave de API, crear escenarios en Make, configurar webhooks y probar las cargas útiles.

Descargar y almacenar archivos multimedia

Las URL de video y audio de las cargas útiles de los webhooks son enlaces de descarga directa. Puedes obtener estos archivos mediante programación o manualmente.

Prácticas recomendadas para gestionar archivos multimedia

• Descarga de inmediato: los archivos multimedia caducan según el período de retención de tu plan (consulta más abajo). Descarga las grabaciones importantes a tu propio almacenamiento en cuanto lleguen los webhooks.

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

• Descarga de forma asíncrona: usa tareas en segundo plano o colas para descargar archivos sin bloquear tu endpoint de webhook.

• Verifica las descargas: comprueba los códigos de respuesta HTTP y el tamaño de los archivos para confirmar que las transferencias se realizaron correctamente.

Para conocer las opciones de descarga manual y los flujos de trabajo desde el navegador, consulta Cómo descargar respuestas de video y audio de las solicitudes.

Períodos de retención de videos

Las grabaciones se conservan durante 30 días en los planes One Job y Startup, y durante 90 días en el plan Growth. Puedes ampliar el almacenamiento de videos desde la pestaña Facturación de tu perfil, en Ampliar período de almacenamiento de videos, en incrementos de 30 días. La ampliación solo se aplica a los videos grabados después de la compra.

Solución de problemas comunes

Faltan las URL de video en la carga útil del webhook

Asegúrate de que el interruptor Incluir respuestas, URL de videos y transcripciones esté activado en Configuración avanzada, dentro de la configuración de webhook del puesto. Sin esta opción, las cargas útiles contienen los metadatos del solicitante y un arreglo answers vacío.

El endpoint no recibe datos

Comprueba lo siguiente:

• La URL de tu endpoint es de acceso público mediante HTTPS

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

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

• Usa Probar activador en la configuración de webhook del puesto para enviar una carga útil de muestra

Los videos caducaron o los enlaces devuelven 404

Las grabaciones se eliminan cuando vence el período de retención de tu plan: 30 días en One Job y Startup, y 90 días en Growth. Compra almacenamiento adicional desde la pestaña Facturación de tu perfil para conservar durante más tiempo las nuevas grabaciones.

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

Las transcripciones se incluyen en el campo transcript de cada respuesta cuando están activadas para la pregunta en la configuración de tu puesto. Si los campos de transcripción llegan vacíos, comprueba que la pregunta tenga las transcripciones activadas.

El webhook se desactivó automáticamente tras varios fallos

Después de 5 fallos de entrega terminales consecutivos, Hirevire desactiva automáticamente el webhook para proteger tu endpoint. Una entrega que todavía se está reintentando no cuenta para este límite. Cuando esto ocurre, verás un aviso en la configuración de webhook del puesto que indica:

Este webhook se desactivó automáticamente tras varios fallos

Si se muestra una marca de tiempo, incluye 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 puesto, el endpoint y el último error registrado.

Volver a activar un webhook desactivado:

1. Ve a Puestos y selecciona el puesto afectado

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é reparado

5. Haz clic en Volver a activar

Hirevire vuelve a activar el webhook y muestra la confirmación Webhook reactivado.

Reintentar una entrega de webhook fallida

Cada entrega puede tener hasta tres intentos: el intento inicial, un reintento después de 1 minuto y otro después de 10 minutos. Se vuelven a intentar los fallos de transporte, los tiempos de espera agotados, las respuestas HTTP 429 y las respuestas HTTP 500 o superiores; los demás estados de error son terminales desde el primer intento.

También puedes volver a intentar entregas fallidas individuales desde los registros del panel. Para ver el calendario completo de reintentos, los filtros de registros y el comportamiento de reactivación, consulta Registros de webhooks y reintentos de entrega.

Verificar las firmas de los webhooks

Cuando configuras un secreto de firma en el webhook de un puesto, 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 para cada puesto en la misma configuración de Webhook que la URL y los activadores.

1. Abre Puestos, selecciona el puesto 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.

Encabezados que envía Hirevire

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

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 genera la firma

Hirevire crea una cadena y luego la firma:

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

2. Añade un punto (.).

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

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

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

Pasos para verificar en tu endpoint

1. Lee el cuerpo sin procesar de la solicitud como bytes o como una cadena antes de analizar el JSON, ya que ese análisis podría cambiar 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 el HMAC-SHA256 de timestamp + "." + rawBody con tu secreto de firma y obtén el resumen en hexadecimal.

5. Compara tu resumen con el valor sha256 del encabezado. Acepta la solicitud solo si coinciden.

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 de los webhooks contienen información confidencial de los candidatos. Sigue estas directrices:

• Usa endpoints HTTPS: cifra los datos en tránsito para evitar que sean interceptados.

• Verifica las firmas: configura 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 retención de datos: conserva los videos y la información personal de los candidatos solo durante el tiempo necesario para tomar decisiones de contratación; después, elimínalos de acuerdo con los requisitos del RGPD y de privacidad.

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

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

Hirevire elimina los archivos multimedia grabados cuando vence el período de retención de tu plan. Informa a los candidatos sobre tus prácticas de gestión de datos en la publicación del puesto o en tu política de privacidad.

Próximos pasos

• Configura webhooks para tus puestos activos

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

• Descarga los videos importantes de los candidatos a tu almacenamiento

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