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.
201
Copy {
"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
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.
Opções de kind
Copy 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.
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.
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.
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.
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
Copy {
"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"
]
}
}
Copy {
"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"
]
}
}
Copy {
"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"
]
}
}
Copy {
"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#
Copy 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
Copy 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
Copy 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
Copy 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
Body
Copy {
"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
200
Copy {
"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
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
200
Copy {
"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
Ping webhook
POST
https://api.acessorh.com.br/v1/integrations/webhook/ping
Descrição do body JSON da request
Exemplo de requisição
Copy {
"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
200
Copy {
"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
200
Copy {
"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"
}
Last updated 9 months ago