Obtener detalles de solicitudes mediante webhooks

Descripción general

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

Esta guía te muestra cómo configurar webhooks, analizar los datos 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 la solicitud 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 del candidato inmediatamente después del envío.

Con el interruptor de respuestas activado, los datos del webhook incluyen:

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

• URL directas de las respuestas de video y audio

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

• Archivos subidos y respuestas de texto

• Respuestas de referencia como datos estructurados

Con el interruptor desactivado, los datos siguen conteniendo todos los metadatos de la solicitud, pero el array answers está vacío.

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 datos JSON. Hirevire reintenta automáticamente las entregas fallidas; consulta Registros de webhooks y reintentos de entrega para conocer el calendario completo de reintentos y qué errores se reintentan.

Si utilizas Make.com, Zapier o herramientas similares, genera primero una URL de webhook desde su plataforma (se explica en la sección de Make.com a continuación).

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

1. Ve a Jobs y selecciona la oferta que quieres supervisar

2. Haz clic en la pestaña Settings

3. Abre la sección Webhook en Custom Webhook Integration

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

Paso 3: Elige los activadores

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

• On new application: Envía los datos cuando un candidato completa y envía su evaluación

• On stage change: Envía los datos 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

Abre Advanced Settings y activa Include answers, video urls and transcripts para recibir todos los detalles de la solicitud, incluidos los enlaces multimedia y las transcripciones de IA. Sin esta configuración, los datos contienen los metadatos básicos del solicitante y un array answers vacío.

Paso 5: Prueba y guarda

Haz clic en Test trigger para enviar datos de ejemplo a tu endpoint. La prueba respeta el interruptor de respuestas: cuando está desactivado, los datos de ejemplo tienen un array answers vacío. Comprueba que tu sistema recibe y procesa los datos correctamente y, a continuación, haz clic en Save.

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

Comprender 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

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". Con las respuestas activadas, los datos incluyen todas las respuestas, las URL multimedia y las transcripciones.

Stage change event: Se activa cuando mueves manualmente una solicitud entre etapas después del envío. Esto incluye moverla de "To be reviewed" a etapas personalizadas como "Interview" o "Rejected". Los datos incluyen tanto la etapa anterior como la actual.

Qué NO activa los webhooks

Estos estados del candidato no activan webhooks:

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

• In-progress: El candidato ha comenzado a completar sus datos, pero no ha enviado todas las respuestas. Consulta Por qué tenemos muchas solicitudes en "In-Progress" 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.

Comprender los datos de los webhooks

Cuando se activa un webhook, Hirevire envía una solicitud POST con datos JSON que contienen la solicitud.

Campos principales de los datos

Metadatos del solicitante:

• id: Identificador único de la solicitud

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

• 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

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

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

• 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

Array de respuestas: Cada objeto de respuesta siempre contiene:

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

• id: Identificador de la respuesta

• transcript: Texto de la transcripción generada por IA o una cadena vacía cuando no existe ninguna transcripción

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

Los campos adicionales dependen de responseType:

Respuestas de referencias

Cuando una pregunta utiliza el tipo de respuesta References, el campo value de la respuesta es un array 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, cuando se proporcionan

• relationshipDetail: Detalles adicionales de la relación, presentes cuando el candidato selecciona Other como relación

Los valores de relationship admitidos son Supervisor, Co-worker, Mentor, Client y Other. Las respuestas de referencias solo se incluyen cuando Include answers, video urls and transcripts está activado en el webhook de la oferta. Consulta Cómo recopilar referencias en una oferta de empleo para configurar las preguntas.

Ejemplos de datos de webhooks

Ejemplo de datos 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",
  "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..."
    }
  ]
}

En una entrega por cambio de etapa, los datos tienen la misma estructura, pero previousStage contiene la etapa desde la que se movió la solicitud; por ejemplo, "previousStage": "New" y "currentStage": "Interview". previousStage es null para los nuevos envíos.

Integrar con Make.com

Para consultar una guía completa paso a paso sobre cómo conectar Hirevire con Make.com (antes Integromat), visita Conectar Hirevire con Make.com. Esta guía explica cómo generar tu clave de API, crear escenarios de Make, configurar webhooks y probar los datos.

Descargar y almacenar archivos multimedia

Las URL de video y audio de los datos del 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 (consulta más abajo). Descarga las grabaciones importantes en 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 asíncrona: Utiliza 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 garantizar que las transferencias se han realizado correctamente.

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

Periodos de conservació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 Billing de tu perfil, en Extend Video Storage Duration, en múltiplos de 30 días. La ampliación solo se aplica a los videos grabados después de la compra.

Solución de problemas habituales

Faltan las URL de video en los datos del webhook

Asegúrate de que el interruptor Include answers, video urls and transcripts esté activado en Advanced Settings, dentro de la configuración de webhook de tu oferta. Sin esta opción, los datos contienen los metadatos del solicitante y un array answers vacío.

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

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

• Utiliza Test trigger en la configuración de webhook de la oferta para enviar datos de ejemplo

Los videos han caducado o los enlaces devuelven 404

Las grabaciones se eliminan después del periodo de conservació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 Billing de tu perfil para conservar las nuevas grabaciones durante más tiempo.

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

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

El webhook se desactivó automáticamente tras varios errores

Después de 5 errores terminales de entrega 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 banner en la configuración de webhook de la oferta que dice:

Este webhook se desactivó automáticamente tras varios errores

Si se muestra una marca de tiempo, incluye la fecha y hora en que se desactivó el webhook. Hirevire también envía al propietario de la organización un correo electrónico que contiene la oferta, el endpoint y el último error registrado.

Volver a activar un webhook desactivado:

1. Ve a Jobs y selecciona la oferta afectada

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á solucionado

5. Haz clic en Re-enable

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

Reintentar una entrega de webhook fallida

Cada entrega tiene hasta tres intentos: el intento inicial, un reintento después de 1 minuto y otro después de 10 minutos. Los errores de transporte, los tiempos de espera, las respuestas HTTP 429 y las respuestas HTTP 500 o superiores se reintentan; los demás estados fallidos son terminales desde el primer intento.

También puedes reintentar entregas fallidas individuales desde los registros del panel. Para consultar el calendario completo de reintentos, los filtros de registros y el comportamiento de reactivación, visita Registros de webhooks y reintentos de entrega.

Verificar las firmas de los webhooks

Cuando configuras un secreto de firma en el webhook de una oferta, 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 los datos.

Configurar un secreto de firma

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

1. Abre Jobs, selecciona la oferta y ve a Settings → Webhook.

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

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

4. Haz clic en Save.

Cabeceras que envía Hirevire

Cuando se configura 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 JSON sin procesar de la solicitud 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 resumen en hexadecimal.

En resumen: cadena firmada = timestamp + "." + rawBody, 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 analizar cualquier JSON que pueda modificar 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 utilizando 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

Los datos de los webhooks contienen información confidencial de los candidatos. Sigue estas directrices:

• Utiliza 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 mediante los pasos de verificación anteriores.

• Limita la conservación de datos: Almacena los videos y la información personal de los candidatos solo durante el tiempo necesario para tomar decisiones de contratación y, después, elimínalos conforme a 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 los archivos multimedia grabados cuando vence el periodo de conservación de tu plan. Comunica tus prácticas de gestión de datos a los candidatos en tu oferta de empleo o política de privacidad.

Próximos pasos

• Configura webhooks para tus ofertas activas

• Prueba los datos con tus herramientas de automatización

• Descarga los videos importantes de los candidatos en tu almacenamiento

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