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

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

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

basic

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

apiKey

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

Put webhook

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

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

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

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

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

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

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

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

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

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