Fluxo de Envio e Retorno para Plataforma de Validações ou Exames externos
Este fluxo contempla o envio de candidaturas cadastradas na Gupy para plataformas externas de validações ou exames e o retorno das informações disponibilizadas pelo sistema terceiro.
Esse fluxo possibilita saber se a pessoa candidata foi aprovada ou não nas validações, além de suas notas ou informações adicionais que podem ser necessárias.
O retorno do sistema terceiro utilizado para os testes será inserido na plataforma em formato de TAGs na candidatura da pessoa ou comentários na timeline.
Este fluxo utiliza webhookPara implementar integrações a partir de webhooks é necessário uma configuração prévia através da própria API Gupy: Veja aqui mais informações sobre o recebimento de webhooks
Atenção!A URL usada para receber o webhook DEVE ser um endereço HTTPS válido, exposto publicamente. Para configurar o webhook, consulte Webhook Configuração .
URLs com alta taxa de erro (100% dos erros nos últimos 7 dias) serão removidas sem aviso prévio.
O sistema garante pelo menos uma entrega, então podem haver várias notificações do mesmo evento, use a propriedade id para identificar duplicatas.
Não há garantia de ordem de entrega, use a propriedade date para verificar qual evento aconteceu primeiro e classifique os eventos. Exemplo: um application.moved pode ser notificado antes de application.created
NÃO USE serviços como requestcatcher, eles podem expor dados.
Definição de tags
Antes de criar as tags, é necessário definir o que ela informará para a pessoa recrutadora. Elas devem ser criadas a partir da relação que o cliente tem no sistema provedor.
Veja alguns exemplos de definição:
- Enviar tags de "apto" e "inapto" para sinalizar se a pessoa deve continuar ou não no processo seletivo
- Enviar tags apenas de "inapto" e não enviar tags para os que estão aptos ou vice-versa
Esse processo precisa ser definido com o RH.
Caso o retorno do sistema terceiro seja muito grande para uma TAG é possível inseri-lo na forma de comentário na timeline do candidato.
Habilitando Endpoints
Para utilizar este fluxo, é necessário utilizar o Bearer Token gerado nas configurações avançadas da plataforma. Acesse nossa seção de autenticação para saber como gerar o token de autenticação.
Abaixo encontra-se uma sugestão dos endpoints que devem ser habilitados obrigatoriamente para o funcionamento perfeito deste fluxo.

Definição de etapas
Antes de iniciar o fluxo, é necessário definir em qual etapa as pessoas candidatas irão passar pela avaliação escolhida, pois a movimentação do candidato para essa etapa é o evento gatilho de disparo do webhook.
Caso seja necessário criar uma etapa, veja nesse guia como fazer isso. Lembrando que o nome da etapa fica público para todo os participantes do processo seletivo.
Fluxo de integração
Configurar webhook application moved
- Acessar POST Webhooks (https://developers.gupy.io/reference/createwebhook)
- Alterar parâmetro action para application.moved
- Inserir no postbackUrl o endereço para onde será direcionado o webhook
- Inserir bearer token e depois em "Try it!"

Exemplo de requisição
curl --request POST \
--url https://api.gupy.io/api/v1/webhooks \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"action": "application.moved",
"status": "active",
"postbackUrl": "https://urldo.agenteintegrador.net",
"techOwnerName": "Nome Sobrenome",
"techOwnerEmail": "[email protected]"
}
'
Exemplo de resposta
{
"id": "d5b2eca6-09c5-4014-9eb8-1d729dd2e3d6",
"action": "application.completed",
"postbackUrl": "https://urldo.agenteintegrador.net",
"status": "active"
}
Recebimento no agente integrador
O webhook application moved event dispara sempre que a pessoa candidata é movida entre as etapas do processo seletivo, sendo necessário filtrar pela etapa desejada.
O agente integrador receberá os dados webhook (conforme contrato-JSON application moved) e será necessário guardar os seguintes campos:
- body.data.job.id,
- body.data.application.id
- body.data.application.currentStep.name
Operações na plataforma de validações
Após o recebimento das informações do webhook, é necessário uma ação por parte da pessoa candidata, sendo necessário que ela:
- Acesse o sistema de validações ou receba a data dos exames;
- Responda todos as perguntas necessárias ou compareça aos exames marcados;
- Receba um resultado das validações ou exames.
Apenas após a última ação da pessoa candidata é possível continuar para o fluxo de inserção de tags ou de comentários na timeline.
Parâmetros obrigatórios
Para fazer o envio das tags, é necessário obter a jobId da vaga e a applicationId da pessoa candidata, pois são parâmetros obrigatórios. Para isso:
- Envie requisição para o endpoint GET Jobs
- Utilize o parâmetro currentStep.name para filtrar apenas por pessoas candidatas que estão na etapa onde ficarão elegíveis para a verificação.
- Envie requisição para o endpoint GET applications
Inserindo retorno como TAGs na candidatura
Envie requisição para o endpoint PUT tags
Exemplo de requisição
curl --request PUT \
--url https://api.gupy.io/api/v1/jobs/123456/applications/654321/tags \
--header 'accept: application/json' \
--header 'authorization: Bearer XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
--header 'content-type: application/json' \
--data '{"name":"Apto"}'
Exemplo de resposta
{
"id": 34486644,
"candidateId": 33172137,
"applicationId": 654321,
"jobId": 123456,
"name": "Apto"
}
Inserindo retorno como comentário na timeline
Envie requisição para o endpoint Creating a comment in candidate timeline
Exemplo de requisição
curl --request POST \
--url https://api.gupy.io/api/v1/jobs/269691/applications/33428140/comments \
--header 'accept: application/json' \
--header 'authorization: Bearer XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
--header 'content-type: application/json' \
--data '
{
"text": "O candidato realizou os testes técnicos e foi aprovado"
}
'
Exemplo de resposta
{
"id": 12307223,
"userId": 22011,
"hidden": false,
"text": "O candidato realizou os testes técnicos e foi aprovado",
"createdAt": "2023-05-13T10:24:26.838Z",
"updatedAt": "2023-05-13T10:24:26.838Z"
}
Reprovando a pessoa candidata
Pode ser que o fluxo de negócio implique na reprovação da pessoa candidata caso ela não tenha atingido os critérios de validação/exames. Para realizar a reprovação siga as instruções abaixo:
- Acesse o endpoint moving an application
- Insira o jobId e applicationId que foram enviados pelo webhook
- Escolha o novo status como "reproved"
- Escolha o motivo da reprovação
Exemplo de requisição:
curl --request PATCH \
--url https://api.gupy.io/api/v1/jobs/123456/applications/54734634 \
--header 'accept: application/json' \
--header 'authorization: Bearer XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
--header 'content-type: application/json' \
--data '
{
"status": "reproved",
"disapprovalReason": "test_result_below_cutoff"
}
'
Possíveis erros
Recebimento no agente integrador
O ambiente precisa estar público para poder receber os dados, caso contrário, acontecerá um erro.
Como ficará essa integração na Gupy?
- TAG na plataforma

- Comentário na timeline na plataforma:

Updated 3 months ago