Obtener detalles de la solicitud 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 la carga completa de la solicitud cuando los candidatos envían respuestas o pasan entre etapas.

Esta guía te muestra cómo configurar webhooks, analizar cargas de solicitud que incluyen URLs 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 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 solicitud, incluidos:

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

• URLs directas de respuesta en video 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 webhooks por puesto para enviar los datos de la solicitud a tu endpoint.

Paso 1: Prepara tu endpoint

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

Si usas Make.com, Zapier o herramientas similares, genera primero 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 puesto

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

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 desencadenantes

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

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

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

Puedes habilitar ambos desencadenantes al mismo tiempo.

Paso 4: Habilita 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 postulante.

Paso 5: Probar y guardar

Haz clic en Test trigger para enviar una muestra de carga 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.

Comprender los desencadenantes del webhook

Los webhooks se activan solo 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é desencadena los webhooks

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

Evento de cambio de etapa: 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 incluye tanto la etapa anterior como la actual.

Qué NO desencadena webhooks

Estos estados del candidato no activan webhooks:

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

• In-progress: El candidato comenzó a completar los datos, 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.

Muestras de cargas útiles del webhook

Aquí tienes ejemplos de carga para cada tipo de desencadenante que te ayudarán a crear integraciones.

Carga 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 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 nuevos envíos 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 JSON que contiene la solicitud completa.

Campos clave de la carga

Metadatos del postulante:

• id: ID único de la solicitud

• applicantName, applicantEmail, applicantContactNumber: Datos de contacto

• applicantResumeURL: Enlace directo de descarga 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

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 subidos

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

Integrar con Make.com

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

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

Descargar y almacenar archivos multimedia

Las URLs de video y audio en las cargas del webhook son enlaces de descarga directa. Puedes obtener estos archivos mediante programación o manualmente.

Mejores prácticas para gestionar medios

• Descarga inmediatamente: Los archivos multimedia caducan según el período de retención de tu plan (90 días en todos los planes). Descarga las grabaciones críticas 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 GDPR si procesas candidatos de la UE.

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

• Verificar descargas: Comprueba los códigos de respuesta HTTP y los tamaños de archivo para asegurarte de que las transferencias se completaron correctamente.

Para opciones de descarga manual y flujos de trabajo basados en navegador, consulta How to download video and audio responses from applications.

Solución de problemas comunes

La carga 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 de webhook de tu puesto. Los webhooks básicos solo envían metadatos del postulante sin detalles de las respuestas.

El endpoint no recibe datos

Revisa lo siguiente:

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

• Tu servidor devuelve un código de estado 200 en 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 muestra de carga

Los videos expiraron 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 puesto) 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 habilitadas en la configuración de preguntas de tu puesto.

Webhook deshabilitado automáticamente tras fallos repetidos

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

Este webhook se deshabilitó automáticamente después de fallos repetidos

Si se muestra una marca de tiempo, incluirá la fecha y hora en que se deshabilitó 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 habilitar un webhook deshabilitado:

1. Ve a Jobs y selecciona el puesto afectado

2. Haz clic en la pestaña Settings

3. Abre la sección Webhook

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

5. Haz clic en Re-enable

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

Reintentar una entrega de webhook fallida

Puedes reintentar entregas de webhook fallidas individuales 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.

Seguridad y retención de datos

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

• Usa endpoints HTTPS: Cifra los datos en tránsito para evitar interceptaciones

• Valida las fuentes del webhook: Verifica que las solicitudes provengan de los servidores de Hirevire (comprueba los rangos de IP o implementa firmas de webhook si están disponibles)

• Limita la retención de datos: Almacena los videos de los candidatos y la información personal solo durante el tiempo necesario para las decisiones de contratación y luego elimínalos según los requisitos del GDPR 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: Haz un seguimiento de quién accedió a los datos de la solicitud y cuándo

Hirevire elimina automáticamente los datos de los candidatos después de que expire 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 en los webhooks

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

Próximos pasos

• Configura webhooks para tus puestos activos

• Prueba las cargas con tus herramientas de automatización

• Descarga los videos críticos de los candidatos a tu almacenamiento

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