Importante lembrar que toda a definição das regras de negócio e configuração do conteúdo das mensagens são realizadas diretamente no serviço contratado pelo cliente.

Alguns serviços comuns no mercado: Takeblip, infobip, Callbell

📘

Esse fluxo utiliza webhook

Para realizar integrações utilizando Webhooks é necessário um agente integrador (middleware) para receber e tratar os dados.

Para 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;

Não é possível fechar VPN como rota para entrega do Webhook;

URLs com alta taxa de erro (100% dos erros nos últimos 7 dias) serão removidas sem aviso prévio.

O Webhook espera uma resposta em 30.000 ms. Caso a resposta não tenha ocorrido antes deste tempo, consideramos um timeout, consequentemente, um erro.

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.

Quando setamos algum valor no clientHeaders, o header padrão 'Content-type: application/json;charset=utf-8' não é mais enviado, pois o valor dos headers passa a ser o que foi definido. Se for necessário que o Content-type tenha sempre o valor padrão, recomendamos passá-lo junto no clientHeaders.

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.

Fluxo de integração

1. Configurar os webhook "application.created" para envios de mensagem quando o candidato se candidatar a uma vaga e "application.moved" para quando o candidato for movido de etapa

• Acessar endpoint POST Webhooks (https://developers.gupy.io/reference/createwebhook)
• Ajustar o parâmetro "action" para application.created
• Inserir no "postbackUrl" o endereço (URL segura) para onde será direcionado o webhook
• Inserir o Bearer token e então no botão "Try it!"

Exemplo de requisição

curl --request POST \
     --url https://api.gupy.io/api/v1/webhooks \
     --header 'accept: application/json' \
     --header 'authorization: Bearer XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
     --header 'content-type: application/json' \
     --data '
{
     "action": "application.created",
     "status": "active",
     "postbackUrl": "https://urldo.agenteintegrador.net",
     "techOwnerName": "Nome Sobrenome",
     "techOwnerEmail": "[email protected]"
}
'

Exemplo de resposta para um webhook cadastrado com sucesso

{
  "id": "d5b2eca6-09c5-4014-9eb8-1d729dd2e3d6",
  "action": "application.completed",
  "postbackUrl": "https://urldo.agenteintegrador.net",
  "status": "active"
}

Realizar o mesmo procedimento acima para o webhook application.moved

Recebimento no agente integrador

O agente integrador receberá os dados webhook (conforme contrato-JSON application created) e

será necessário guardar os seguintes campos:

• data.candidate.name
• data.candidate.email
• data.identificationDocument
• data.candidate.mobileNumber
• data.currentStep.name (criar regra para todas as etapas, exceção "Contratação")
• date
• data.job.name
• id
• job.id
• application.id

Para saber a etapa anterior em que o candidato estava, guarde também o campo previousStep.Name.

Como testar

A Gupy não possui ambiente de testes. Por isso, quando surge a necessidade de um teste seguro, recomendamos que crie Vagas e Candidatos testes. No caso da Vaga, atentar-se para preencher com dados válidos para que a integração funcione, como o Código do cargo alinhado com o Centro de Custo correto. Para os Candidatos testes, é necessário gerar valores válidos também, como CPF e Celular dentro do formato adequado, é possível encontrar na internet plataformas geradoras de dados como esses. Outra dica é utilizar e-mails descartáveis, para que não seja necessário criar diversas contas de e-mails para testar diferentes cenários.

Possíveis erros

Recebimento no agente integrador
O endpoint que recebe o Webhook precisa estar público para poder receber os dados, caso contrário, acontecerá um erro na entrega.

Dados inválidos
Mesmo com o preenchimento dos dados ocorrendo via integração, o sistema mantém as validações de campos, gerando erros na inserção de dados que não são coerentes, como um CPF em formato inválido.

Campos obrigatórios
Caso o sistema possua campos obrigatórios, é importante mapeá-los para garantir seu envio durante a integração.