Comment on page

Webhooks

Criação e listagem de webhooks

Webhook é o serviço de notificação sistêmica, que permite a integração assíncrona entre sistemas, notificando o outro sistema através de um gatilho.
Ao configurar um webhook você poderá utilizar alguns modelos de autenticação, que garantem maior confiança na fonte que está se comunicando com o seu endpoint.
O webhook  possui uma função de Retry, a qual irá realizar uma nova tentativa a cada 5 segundos por 3 dias (quando a requisição será abandonada).
Durante o período, todas as requisições deste webhook que falharem ficarão em fila, sendo apenas uma tentativa (desta configuração de webhook) a cada 5 segundo.
Uma vez que o serviço receba o Ok de seu endpoint, as requisições serão liberadas em sequência, ou seja, uma de cada vez.
post
https://api.acessorh.com.br
/v1/integrations/webhook
Create webhook
​Descrição do body JSON da request​
​Exemplo de requisição​
​Calcular assinatura do payload​
​Exemplo de callback​
Descrição do body JSON da request
Chave
Tipo
Descrição
account
required
string
UID da empresa desejada.
unit
optional
string
UID da filial desejada.
authorization
optional
object
Método de autenticação a ser realizado.
data
required
object
Configuração do callback que 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.
Chave
Tipo
Descrição
kind
required
string (options)
Tipo da autenticação que será realizada.
data
required
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.
Chave
Tipo
Descrição
username
required
string
Nome do usuário.
password
required
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
required
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.
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.
Chave
Tipo
Descrição
url
required
string
URL para a execução do callback. Aceito apenas
endereços HTTPS.
events
required
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)
Exemplos de requisição
secret
basic
apiKey
Put webhook
​Mais informações​
{
  	"account": "2d9174c4-06b7-4956-a5dc-8824d8a2f49e",
  	"unit": "82930d53-e99a-4927-b31e-4fdc7090395d",
  	"authorization": {
  		"kind": "secret",
  		"data": {
  			"secret": "tme0dQq1CIDm4PYsfK!d"
  		}
  	},
  	"data": {
  		"url": "https://api.teste.com.br/callback",
  		"events": [
  			"position-created",
  			"position-archived",
  			"position-completed"
  		]
  	}
}
​Mais informações​
{
	"account": "2d9174c4-06b7-4956-a5dc-8824d8a2f49e",
        "unit": "82930d53-e99a-4927-b31e-4fdc7090395d",
	"authorization": {
		"kind": "basic",
		"data": {
                       "username": "teste",
		       "password": "1234"
		}
	},
	"data": {
		"url": "https://api.teste.com.br/callback",
		"events": [
			"position-created",
			"position-archived"
		]
	}
}
​Mais informações​
{
	"account": "2d9174c4-06b7-4956-a5dc-8824d8a2f49e",
        "unit": "82930d53-e99a-4927-b31e-4fdc7090395d",
	"authorization": {
		"kind": "apiKey",
		"data": {
                       "key": "password123",
		       "prefix": "X-Api-Key" // opcional
		}
	},
	"data": {
		"url": "https://api.teste.com.br/callback",
		"events": [
			"position-created",
			"position-archived"
		]
	}
}
​Mais informações​
{
	"id": "b712a527-efec-4e02-83d5-95cbd7c269f9",
	"account": "2d9174c4-06b7-4956-a5dc-8824d8a2f49e",
        "unit": "82930d53-e99a-4927-b31e-4fdc7090395d",
	"authorization": {
		"kind": "apiKey",
		"data": {
                       "key": "password123",
		       "prefix": "X-Api-Key"
		}
	},
	"data": {
		"url": "https://api.teste.com.br/callback",
		"events": [
			"position-created",
			"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 3
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
Exemplo de callback
Headers
Header
Descrição
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"
}
put
https://api.acessorh.com.br
/v1/integrations/webhook
Update webhook
​Descrição do body JSON da request​
Descrição do body JSON da request
Chave
Tipo
Descrição
id
required
string
UID do webhook a ser atualizado.
account
required
string
UID da empresa do webhook a ser atualizado.
unit
optional
string
UID da filial a ser atualizado no webhook.
​authorization​
optional
object
Método de autenticação a ser atualizado.
​data​
optional
object
Configurações do webhook que serão atualizados.
Para atualização, pelo menos um dos campos unit , authorization edata deverão ser preenchidos.
Qualquer um dos campos unit , authorization e data , caso não preenchidos, manterão as informações anteriores.
​Exemplo de requisição​
get
https://api.acessorh.com.br
/v1/integrations/webhooks
List webhooks
Caso não seja inserido os parâmetros limit e skip , os valores padrões serão, respectivamente, 100 e 0.
O parâmetro limit tem o seu valor máximo como 100.
delete
https://api.acessorh.com.br
/v1/integrations/webhook
Delete webhook
post
https://api.acessorh.com.br
/v1/integrations/webhook/ping
Ping webhook
​Descrição do body JSON da request​
​Exemplo de requisição​
Descrição do body JSON da request
Chave
Tipo
Descrição
id
required
string
UID do webhook que será testado.
account
required
string
UID da empresa do webhook que será testado.
Exemplo de requisição
{
	"id": "b712a527-efec-4e02-83d5-95cbd7c269f9",
	"account": "2d9174c4-06b7-4956-a5dc-8824d8a2f49e"
}
get
https://api.acessorh.com.br
/v1/integrations/webhook/deliveries
List webhook deliveries
get
https://api.acessorh.com.br
/v1/integrations/webhook/delivery
Get webhook delivery

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

Anexos

Modelo de carta

Last modified 6mo ago

Header	Descrição
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