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.

Create webhook

POST https://api.acessorh.com.br/v1/integrations/webhook

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

Headers

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

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"
}

Descrição do body JSON da request

account*	string	UID da empresa desejada.
unit	string	UID da filial desejada.
authorization	object	Método de autenticação a ser realizado.
data*	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*	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.

Chave	Tipo	Descrição
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.

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*	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).

Exemplos de requisição

secret

{
  	"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"
  		]
  	}
}

basic

{
	"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"
		]
	}
}

apiKey

{
	"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"
		]
	}
}

Put webhook

{
	"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

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"
}

Update webhook

PUT https://api.acessorh.com.br/v1/integrations/webhook

Headers

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

200 OK

{
    "account": "2d9174c4-06b7-4956-a5dc-8824d8a2f49e",
    "unit": "82930d53-e99a-4927-b31e-4fdc7090395d",
    "authorization": {
        "kind": "basic"
    },
    "data": {
        "url": "https://api.teste.com.br/callback",
        "events": [
            "position-created",
            "position-archived"
        ]
    },
    "uid": "0a22e148-6610-4d38-bcb7-20bbc465d43c"
}

Descrição do body JSON da request

Chave	Tipo	Descrição
id*	string	UID do webhook a ser atualizado.
account*	string	UID da empresa do webhook a ser atualizado.
unit*	string	UID da filial a ser atualizado no webhook.
authorization*	object	Método de autenticação a ser atualizado.
data*	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.

List webhooks

GET https://api.acessorh.com.br/v1/integrations/webhooks

Query Parameters

Name	Type	Description
account*	string	UID da empresa onde os webhooks serão listados.
skip	integer	Indica a quantidade de webhooks que serão pulados (paginação).
limit	integer	Limite de webhooks que serão listados (paginação).

Headers

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

200 OK

{
    "total": 2,
    "results": [
        {
            "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"
        },
        {
            "account": "2d9174c4-06b7-4956-a5dc-8824d8a2f49e",
            "authorization": {
                "kind": "basic"
            },
            "data": {
                "url": "https://api.teste.com.br/callback/applied",
                "events": [
                    "position-applied"
                ]
            },
            "uid": "32b3f3d0-59dc-4cf1-9b4d-4ffcd04a14e4",
            "unit": "82930d53-e99a-4927-b31e-4fdc7090395d"
        }
    ]
}

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 webhook

DELETE https://api.acessorh.com.br/v1/integrations/webhook

Query Parameters

Name	Type	Description
uid*	string	UID do webhook a ser removido.
account*	string	UID da empresa onde o webhook será removido.

Headers

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

200 OK

Ping webhook

POST https://api.acessorh.com.br/v1/integrations/webhook/ping

Headers

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

204

Descrição do body JSON da request

Chave	Tipo	Descrição
id*	string	UID do webhook que será testado.
account*	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"
}

List webhook deliveries

GET https://api.acessorh.com.br/v1/integrations/webhook/deliveries

Query Parameters

Name	Type	Description
uid*	string	UID do webhook onde as entregas serão listadas.
account**	string	UID da empresa na qual o webhook pertence.
skip	string	Indica a quantidade de entregas que serão puladas (paginação)
limit	string	Limite de entregas que serão listadas (paginação)

Headers

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

200 OK

{
    "total": 2,
    "results": [
        {
            "account": "2d9174c4-06b7-4956-a5dc-8824d8a2f49e",
            "data": {
                "request": {
                    "headers": {
                        "Accept": [
                            "application/json"
                        ],
                        "Acesso-Delivery-Id": [
                            "c8815dab-d6be-4a8d-9c68-62ee849fed39"
                        ],
                        "Acesso-Signature": [
                            "jZXci/I69WDH5y7Vt2I3daJRWL9jX7pf2eL9+676KWo="
                        ],
                        "Content-Type": [
                            "application/json"
                        ],
                        "User-Agent": [
                            "go-resty/1.11.0 (https://github.com/go-resty/resty)"
                        ]
                    },
                    "payload": {
                        "integration": "0a22e148-6610-4d38-bcb7-20bbc465d43c",
                        "position": "302fc619-2054-448c-a9f8-d1093fcaddf2",
                        "position-number": null,
                        "unit": "8a240932-7c99-40da-aeb8-37a89308c642",
                        "event": "position-archived"
                    }
                },
                "response": {
                    "headers": {
                        "Content-Length": [
                            "202"
                        ],
                        "Content-Type": [
                            "application/json"
                        ],
                        "Date": [
                            "Thu, 26 Dec 2019 16:01:26 GMT"
                        ]
                    },
                    "status": 200,
                    "body": "eyJldmVudCI6InBvc2l0aW9uLWFyY2hpdmVkIiwiaW50ZWdyYXRpb24iOiIwYTIyZTE0OC02NjEwLTRkMzgtYmNiNy0yMGJiYzQ2NWQ0M2MiLCJwb3NpdGlvbiI6IjMwMmZjNjE5LTIwNTQtNDQ4Yy1hOWY4LWQxMDkzZmNhZGRmMiIsInBvc2l0aW9uLW51bWJlciI6bnVsbCwidW5pdCI6IjhhMjQwOTMyLTdjOTktNDBkYS1hZWI4LTM3YTg5MzA4YzY0MiJ9Cg=="
                }
            },
            "id": "c8815dab-d6be-4a8d-9c68-62ee849fed39",
            "integration": "0a22e148-6610-4d38-bcb7-20bbc465d43c",
            "organization": "896ffd1d-a3a9-43df-a2e8-eed057fe40e6",
            "timestamp": "2019-12-26T16:01:26.225Z",
            "type": "webhook"
        },
        {
            "account": "2d9174c4-06b7-4956-a5dc-8824d8a2f49e",
            "data": {
                "request": {
                    "headers": {
                        "Accept": [
                            "application/json"
                        ],
                        "Acesso-Delivery-Id": [
                            "cb549c0f-ae08-44bc-b729-7d46b9b6c4cc"
                        ],
                        "Acesso-Signature": [
                            "tClrDZ0umoMpVKKz6JpMmKXxeu3BVdU9bcUScKl5b6Q="
                        ],
                        "Content-Type": [
                            "application/json"
                        ],
                        "User-Agent": [
                            "go-resty/1.11.0 (https://github.com/go-resty/resty)"
                        ]
                    },
                    "payload": {
                        "integration": "0a22e148-6610-4d38-bcb7-20bbc465d43c",
                        "position": "302fc619-2054-448c-a9f8-d1093fcaddf2",
                        "position-number": null,
                        "unit": "8a240932-7c99-40da-aeb8-37a89308c642",
                        "event": "position-completed"
                    }
                },
                "response": {
                    "headers": {
                        "Content-Length": [
                            "203"
                        ],
                        "Content-Type": [
                            "application/json"
                        ],
                        "Date": [
                            "Thu, 26 Dec 2019 16:00:59 GMT"
                        ]
                    },
                    "status": 200,
                    "body": "eyJldmVudCI6InBvc2l0aW9uLWNvbXBsZXRlZCIsImludGVncmF0aW9uIjoiMGEyMmUxNDgtNjYxMC00ZDM4LWJjYjctMjBiYmM0NjVkNDNjIiwicG9zaXRpb24iOiIzMDJmYzYxOS0yMDU0LTQ0OGMtYTlmOC1kMTA5M2ZjYWRkZjIiLCJwb3NpdGlvbi1udW1iZXIiOm51bGwsInVuaXQiOiI4YTI0MDkzMi03Yzk5LTQwZGEtYWViOC0zN2E4OTMwOGM2NDIifQo="
                }
            },
            "id": "cb549c0f-ae08-44bc-b729-7d46b9b6c4cc",
            "integration": "0a22e148-6610-4d38-bcb7-20bbc465d43c",
            "organization": "896ffd1d-a3a9-43df-a2e8-eed057fe40e6",
            "timestamp": "2019-12-26T16:00:59.776Z",
            "type": "webhook"
        }
    ]
}

Get webhook delivery

GET https://api.acessorh.com.br/v1/integrations/webhook/delivery

Query Parameters

Name	Type	Description
uid*	string	UID da entrega a ser exibida.
account*	string	UID da empresa do webhook do qual a entrega solicitada pertence.

Headers

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

200 OK

{
    "account": "2d9174c4-06b7-4956-a5dc-8824d8a2f49e",
    "data": {
        "request": {
            "headers": {
                "Accept": [
                    "application/json"
                ],
                "Acesso-Delivery-Id": [
                    "c8815dab-d6be-4a8d-9c68-62ee849fed39"
                ],
                "Acesso-Signature": [
                    "jZXci/I69WDH5y7Vt2I3daJRWL9jX7pf2eL9+676KWo="
                ],
                "Content-Type": [
                    "application/json"
                ],
                "User-Agent": [
                    "go-resty/1.11.0 (https://github.com/go-resty/resty)"
                ]
            },
            "payload": {
                "integration": "0a22e148-6610-4d38-bcb7-20bbc465d43c",
                "position": "302fc619-2054-448c-a9f8-d1093fcaddf2",
                "position-number": null,
                "unit": "8a240932-7c99-40da-aeb8-37a89308c642",
                "event": "position-archived"
            }
        },
        "response": {
            "headers": {
                "Content-Length": [
                    "202"
                ],
                "Content-Type": [
                    "application/json"
                ],
                "Date": [
                    "Thu, 26 Dec 2019 16:01:26 GMT"
                ]
            },
            "status": 200,
            "body": "eyJldmVudCI6InBvc2l0aW9uLWFyY2hpdmVkIiwiaW50ZWdyYXRpb24iOiIwYTIyZTE0OC02NjEwLTRkMzgtYmNiNy0yMGJiYzQ2NWQ0M2MiLCJwb3NpdGlvbiI6IjMwMmZjNjE5LTIwNTQtNDQ4Yy1hOWY4LWQxMDkzZmNhZGRmMiIsInBvc2l0aW9uLW51bWJlciI6bnVsbCwidW5pdCI6IjhhMjQwOTMyLTdjOTktNDBkYS1hZWI4LTM3YTg5MzA4YzY0MiJ9Cg=="
        }
    },
    "id": "c8815dab-d6be-4a8d-9c68-62ee849fed39",
    "integration": "0a22e148-6610-4d38-bcb7-20bbc465d43c",
    "organization": "896ffd1d-a3a9-43df-a2e8-eed057fe40e6",
    "timestamp": "2019-12-26T16:01:26.225Z",
    "type": "webhook"
}