Create webhook

Cria uma integração via webhook que é disparado para a api cadastrada quando determinados eventos relacionados a posição ocorrerem.

POST Url Produção: https://api.acessorh.com.br Url Homologação: https://api.rh.homolog.acesso.io Endpoint: /v1/integrations/webhook

Headers

Name	Type	Description
Authorization*	string	Token de acesso adquirido pela plataforma Identity (bearer).

Descrição do body JSON da request

Obrigatórios

Key	Type	Description
account*	string	UID da empresa desejada.
data*	object	Configuração do callback que será realizado.

Data

Neste ponto serão cadastrados o gatilho ou "trigger" do webhook (motivo pelo qual a chamada do webhook acontecerá), e a URL a qual receberá este aviso.

Key	Type	Description
url*	string	URL para a execução do callback. Aceito apenas endereços HTTPS.
events*	array[string]	Lista de eventos que este webhook irá acompanhar para executar o callback.

Eventos monitorados

Os eventos que poderão ser acompanhados pelos webhooks são:

• position-created (uma posição foi criada na empresa/filial configurada);

• position-applied (um candidato aplicou em uma posição na empresa/filial configurada);

• position-completed (uma posição foi concluída pela análise do Acesso RH ou manualmente pelo DP da empresa/filial configurada);

• position-archived (uma posição foi arquivada pelo DP da empresa/filial configurada);

• position-declined (uma posição que foi declinada da vaga).

Opcionais

Key	Type	Description
unit	string	UID da filial desejada.
authorization	object	Método de autenticação a ser realizado.

Caso o parâmetro unit não seja passado, o callback será executado para todas as filiais da empresa.

Authorization

Para proteger as requisições de callback do webhook, é possível selecionar três opções: basic , secret ou apiKey. Cada uma das opções requer configurações diferentes as quais você pode encontrar mais abaixo.

Em caso de athorization, é obrigatório informar o kind e o data.

Key	Type	Description
kind*	string (options)	Tipo da autenticação que será realizada.
data*	object	Configuração do tipo de autenticação escolhido.

Opções de kind

basic, secret, apiKey

Authorization: data (basic)

Na opção basic, o callback será executado com um header Authorization: basic <credenciais>. As credenciais serão o usuário e senha concatenados por dois pontos (:) e codificados em base64.

Key	Type	Description
username*	string	Nome do usuário.
password*	string	Senha do usuário.

Authorization: data (secret)

Na opção secret, a intenção é que o recebedor consiga se certificar de que o callback recebido foi realizado pelo Acesso RH. Por isso, o callback será executado com um header Acesso-Signature: <assinatura>, sendo a assinatura um hash criado para cada payload. O Acesso RH utiliza um HMAC em conjunto com uma chave sha256 e o secret configurado para calcular e gerar esta assinatura, codificando-a em base64. O mesmo procedimento deve ser realizado na aplicação que receberá esta requisição, comparando a chave gerada e a presente no header. Aqui alguns exemplos de como criar esta verificação.

Chave	Tipo	Descrição
secret*	string	Chave que assinará a requisição.

ApiKey: data (apiKey)

Na opção apiKey, o callback será executado com um header Authorization: <prefix> <key>. Onde o prefix é um campo opcional e key a chave da apiKey. Prefix e key são separados por um espaço em branco.

Chave	Tipo	Descrição
key*	string	Chave da apiKey
prefix	string	Prefixo opcional que pode acompanhar o valor da apiKey.

Exemplos de requisição

Apenas obrigatorios

{
  	"account": "2d9174c4-06b7-4956-a5dc-8824d8a2f49e",
  	"data": {
  		"url": "https://api.teste.com.br/callback",
  		"events": [
  			"position-created",
  			"position-archived",
  			"position-completed"
  		]
  	}
}

secret

basic

apiKey

Put webhook

Exemplo de response

201 OK

{
    "account": "2d9174c4-06b7-4956-a5dc-8824d8a2f49e",
    "authorization": {
        "kind": "secret"
    },
    "data": {
        "url": "https://api.teste.com.br/callback",
        "events": [
            "position-created",
            "position-archived",
            "position-completed"
        ]
    },
    "uid": "a7c001fe-50bb-41cd-a910-da27e538726f",
    "unit": "82930d53-e99a-4927-b31e-4fdc7090395d"
}

Exemplo de callback

Headers

Header	Description
Acesso-Delivery-Id	UID do callback
Acesso-Signature	Caso a opção Secret tenha sido selecionada em Authorization, armazena a assinatura do body da requisição
Authorization	Caso a opção Basic ou ApiKey tenha sido selecionada em Authorization. Para Basic esse header armazena o usuário e senha concatenados e codificados em base64, enquanto para ApiKey será a própria key pura com o prefixo caso tenha sido cadastrado.
Content-Type	Identifica o tipo do body da requisição

Body

{
    "integration": "0a22e148-6610-4d38-bcb7-20bbc465d43c",
    "position": "302fc619-2054-448c-a9f8-d1093fcaddf2",
    "position-number": "ABC123",
    "unit": "8a240932-7c99-40da-aeb8-37a89308c642",
    "event": "position-archived"
}

Calcular assinatura do payload

Abaixo, seguem alguns exemplos de códigos para calcular a assinatura do payload quando a opção secret for configurada nos webhooks:

• C#

• Go

• Java

• Python 3

C#

using System.Security.Cryptography;

private static byte[] HashHMAC(byte[] msg, String secret)
{
    var key = Encoding.ASCII.GetBytes(secret);
    var hash = new HMACSHA256(key);
    return Convert.ToBase64String(hash.ComputeHash(msg));
}

Go

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/base64"
)

func HashHMAC(msg []byte, secret string) string {
	key := []byte(secret)	
	h := hmac.New(sha256.New, key)
	h.Write(msg)
	return base64.StdEncoding.EncodeToString(h.Sum(nil))
}

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.apache.commons.codec.binary.Base64;

public static byte[] HashHMAC(byte[] msg, String secret) {
    Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
    SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
    sha256_HMAC.init(secret_key);
    
    String hash = Base64.encodeBase64String(sha256_HMAC.doFinal(msg));
}

Python

import hashlib
import hmac
import base64

def hashHMAC(msg, secret):
    key = bytes(secret, 'utf-8')

    signature = base64.b64encode(hmac.new(key, message, digestmod=hashlib.sha256).digest())
    return signature