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
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
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)
Chave
Tipo
Descrição
username*
string
Nome do usuário.
password*
string
Senha do usuário.
Authorization: data (secret)
Chave
Tipo
Descrição
secret*
string
Chave que assinará a requisição.
ApiKey: data (apiKey)
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.
Eventos monitorados
Exemplos de requisição
{
"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"
]
}
}
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
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));
}
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))
}
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));
}
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
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
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.
List webhooks
GET
https://api.acessorh.com.br/v1/integrations/webhooks
Query Parameters
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
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"
}
]
}
Delete webhook
DELETE
https://api.acessorh.com.br/v1/integrations/webhook
Query Parameters
uid*
string
UID do webhook a ser removido.
account*
string
UID da empresa onde o webhook será removido.
Headers
Authorization*
string
Token de acesso adquirido pela plataforma Identity (bearer).
Ping webhook
POST
https://api.acessorh.com.br/v1/integrations/webhook/ping
Headers
Authorization*
string
Token de acesso adquirido pela plataforma Identity (bearer).
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
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
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
uid*
string
UID da entrega a ser exibida.
account*
string
UID da empresa do webhook do qual a entrega solicitada pertence.
Headers
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"
}
Atualizado
Isto foi útil?