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

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

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

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#

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

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

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

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

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

Descrição do body JSON da request

Chave

Tipo

Descrição

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

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

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

PreviousAnexos NextModelo de carta

Last updated 2 years ago