Obtener detalles de la candidatura a través de webhooks

Resumen

Hirevire no expone una API pública para obtener datos de candidaturas. En su lugar, utilice webhooks personalizados para recibir automáticamente las cargas de datos completas de las candidaturas cuando los candidatos envíen respuestas o cambien de etapa.

Esta guía le muestra cómo configurar webhooks, analizar las cargas de datos de las candidaturas, incluidas las URLs de vídeo 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 candidatura a su endpoint en tiempo real cuando ocurren eventos. Esto elimina la necesidad de realizar consultas constantes (polling) para buscar actualizaciones y garantiza que sus flujos de trabajo reciban la información del candidato inmediatamente después del envío.

Los webhooks proporcionan detalles completos de la candidatura, que incluyen:

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

• URLs 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

Configure webhooks para cada puesto de trabajo para enviar los datos de la candidatura a su endpoint.

Paso 1: Prepare su endpoint

Su endpoint de webhook debe aceptar solicitudes POST con cargas JSON y devolver un código de estado 200. Hirevire reintentará las entregas fallidas hasta 3 veces.

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

Paso 2: Añada la URL del webhook a su puesto

1. Vaya a Jobs y seleccione el puesto que desea supervisar

2. Haga clic en la pestaña Settings

3. Abra la sección Webhook

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

Paso 3: Elija los activadores

Seleccione cuándo debe Hirevire enviar datos a su 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 mueve manualmente a un candidato entre etapas después del envío

Puede activar ambos activadores simultáneamente.

Paso 4: Active los datos avanzados del webhook

Active la opción "Include answers, video urls and transcripts" para recibir los detalles completos de la candidatura, incluidos los enlaces multimedia y las transcripciones de IA. Sin este ajuste, solo recibirá metadatos básicos del solicitante.

Paso 5: Pruebe y guarde

Haga clic en Test trigger para enviar una carga de datos de muestra a su endpoint. Verifique que su sistema reciba y procese los datos correctamente y luego haga clic en Save.

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

Comprensión de los activadores de webhooks

Los webhooks se activan solo para las candidaturas enviadas, no por la actividad del candidato previa al envío. Esto evita que lleguen datos duplicados o incompletos a sus integraciones.

Qué activa los webhooks

Evento de nuevo envío: Se activa cuando un candidato completa su evaluación y hace clic en enviar. La candidatura pasa del estado "In-progress" al estado "New" o "To be reviewed". La carga de datos del webhook incluye todas las respuestas, URLs multimedia y transcripciones.

Evento de cambio de etapa: Se activa cuando mueve manualmente una candidatura entre etapas después del envío. Esto incluye pasar de "To be reviewed" a etapas personalizadas como "Interview" o "Rejected". La carga de datos incluye tanto la etapa anterior como la actual.

Qué NO activa los webhooks

Estos estados del candidato no activan webhooks:

• Invited: El candidato recibió una invitación pero no ha comenzado la solicitud. Consulte Invitar candidatos de forma masiva para saber cómo funciona esta etapa.

• In-progress: El candidato comenzó a completar los detalles pero no ha enviado todas las respuestas. Consulte ¿Por qué tenemos muchas candidaturas en "In-Progress"? para más contexto.

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

Cargas de datos de ejemplo de los webhooks

Aquí tiene ejemplos de cargas de datos para cada tipo de activador para ayudarle a crear integraciones.

Carga de datos de nuevo envío:

{
  "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 datos 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 para los nuevos envíos y se completa para los cambios de etapa.

Comprensión de las cargas de datos de los webhooks

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

Campos clave de la carga de datos

Metadatos del solicitante:

• id: ID único de la candidatura

• applicantName, applicantEmail, applicantContactNumber: Detalles de contacto

• applicantResumeURL: Enlace de descarga directa al currículum subido

• 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

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

• text: Contenido de la respuesta de texto

• fileURLs: Matriz de enlaces de archivos subidos

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

Integrar con Make.com

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

Esta guía cubre la generación de su clave API, la creación de escenarios en Make, la configuración de webhooks y la prueba de las cargas de datos.

Descargar y almacenar archivos multimedia

Las URLs de vídeo y audio en las cargas de los webhooks son enlaces de descarga directa. Puede obtener estos archivos mediante programación o manualmente.

Mejores prácticas para la gestión de archivos multimedia

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

• Almacenamiento seguro: Almacene los vídeos de los candidatos con los controles de acceso y el cifrado adecuados. Siga las directrices del RGPD si procesa solicitantes de la UE.

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

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

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

Solución de problemas comunes

Faltan las URLs de vídeo en la carga del webhook

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

El endpoint no recibe datos

Compruebe lo siguiente:

• Su URL de endpoint es accesible públicamente a través de HTTPS

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

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

• Pruebe su endpoint con herramientas como Postman o curl utilizando la carga de datos de ejemplo

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

Los archivos multimedia se eliminan después del período de retención de su plan. Actualice a un plan de retención más largo o compre el complemento de extensión de almacenamiento ($9 por puesto) para conservar los archivos durante 30 días adicionales más allá del límite de su plan.

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

Las transcripciones de IA se incluyen en todos los planes de pago. Si las transcripciones no aparecen, verifique que estén habilitadas en la configuración de las preguntas de su puesto.

Seguridad y retención de datos

Las cargas de datos de los webhooks contienen información sensible del candidato. Siga estas directrices:

• Utilice endpoints HTTPS: Cifre los datos en tránsito para evitar interceptaciones

• Validar fuentes de webhooks: Verifique que las solicitudes provienen de los servidores de Hirevire (compruebe los rangos de IP o implemente firmas de webhooks si están disponibles)

• Limitar la retención de datos: Almacene los vídeos de los candidatos y la información personal solo durante el tiempo necesario para las decisiones de contratación, y luego elimínelos según los requisitos del RGPD/privacidad

• Controles de acceso: Restrinja quién puede ver las grabaciones y transcripciones de los candidatos en sus sistemas

• Registros de auditoría: Realice un seguimiento de quién accedió a los datos de la solicitud y cuándo

Hirevire elimina automáticamente los datos de los candidatos una vez que expira su período de retención. Comunique sus prácticas de manejo de datos a los candidatos en su oferta de trabajo o política de privacidad.

Mejoras recientes en los webhooks

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

Próximos pasos

• Configure webhooks para sus puestos activos

• Pruebe las cargas de datos con sus herramientas de automatización

• Descargue los vídeos críticos de los candidatos en su almacenamiento

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