Registro de um novo webhook
stable
Este endpoint permite criar uma configuração para definir quais notificações serão recebidas pelo Webhook Bankly.
Pré-requisito
Para que seja possível utilizar este endpoint, é necessário que:
- O parceiro possua a URI de seu endpoint e a assinatura HMAC implementada.
Nota
Para mais informações, confira a documentação Pré-requisitos para configuração.
Requisição (Request)
Requisição HTTP
POST 'https://api-mtls.sandbox.bankly.com.br/webhooks/configurations' \
--request POST \
--url 'https://api-mtls.sandbox.bankly.com.br/webhooks/configurations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [token]' \
--data-raw '{
"name": "TED_CASH_IN_WAS_CLEARED",
"eventName": "TED_CASH_IN_WAS_CLEARED",
"context": "Ted",
"uri": "https://webhook.site/3635f9f2-e837-41d2-a929-f7f1198120d6",
"privateKey": "NTRlNzM0NGMtNTdmMC00MjQ4LThiZTptM2ZhMDg4NzcwZTA5",
"publicKey": "MGE4NDIwM2ItNmU5Yi00Zjk0LWE5lmEtNWIwMDdiOGVjMjJj"
}
Autorização
Para garantir a segurança nas requisições, todos os endpoints do Bankly utilizam scopes como parte do seu fluxo de autorização.
Esta requisição requer o scope descrito a seguir:
Scope | Descrição |
---|---|
webhook.write | Concede acesso para criar ou atualizar um webhook. |
Cabeçalhos (Headers)
Nome | Descrição |
---|---|
api-version | Obrigatório. Versão da API. Atualmente estamos na versão 1.0. |
Authorization | Obrigatório. Token de autorização do tipo Bearer. |
Parâmetros da rota (Path)
Não é necessário enviar parâmetros no path desta requisição.
Corpo da requisição (Body)
No body, envie os seguintes campos em formato JSON:
Nome | Tipo | Descrição |
---|---|---|
uri | string | Obrigatório. URI da API fornecida pelo parceiro para o recebimento dos eventos. Exemplo: https://meuwebhook/123456. |
privateKey | string | Obrigatório. Chave aleatória gerada pelo parceiro em base64, que somente o Bankly e o dono da chave conhecem. Exemplo: V2ViaG9vayBBY2Vzc29CYW5rbHk=. Lembre-se de que essa chave não é enviada em nenhum evento. |
publicKey | string | Obrigatório. Chave aleatória gerada pelo parceiro e que será enviada pelo Bankly nos cabeçalhos dos eventos de webhook. Exemplo: 95ef924f-eb83-4693-ab03-b07a5e8c60a6 |
name | string | Obrigatório. Nome que o assinante deseja dar para identificar o evento. Esse nome é da escolha do parceiro. Exemplo: TED_CASH_IN. |
eventName | string | Obrigatório. Nome do evento que está sendo assinado. Ele deve ser escrito exatamente conforme apresentamos na documentação de eventos. |
context | string | Obrigatório. Nome do contexto do evento para o qual a configuração de webhook está sendo criada. Ele deve ser escrito exatamente conforme apresentamos na documentação de eventos. |
Importante
Tanto a
privateKey
como apublicKey
devem ter, no máximo, 64 caracteres. Elas podem ser constituídas, por exemplo, por um UUID v4 ou geradas por password generators disponíveis on-line. Para sua segurança, recomendamos que você crie umaprivateKey
e umapublicKey
para cada API.
{
"name": "TED_CASH_IN_WAS_CLEARED",
"eventName": "TED_CASH_IN_WAS_CLEARED",
"context": "Ted",
"uri": "https://webhook.site/3635f9f2-e837-41d2-a929-f7f1198120d6",
"privateKey": "NTRlNzM0NGMtNTdmMC00MjQ4LThiZTptM2ZhMDg4NzcwZTA5",
"publicKey": "MGE4NDIwM2ItNmU5Yi00Zjk0LWE5lmEtNWIwMDdiOGVjMjJj"
}
Nota
É possível configurar a URL de um webhook para mais de um evento, assim como podemos configurar um mesmo evento para duas URLs distintas. No entanto, não é possível criar uma configuração de webhook idêntica a outra configuração já criada.
Resposta (Response)
O status code 201 indicará que a configuração do webhook foi criada com sucesso.
Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:
Nome | Tipo | Descrição |
---|---|---|
data | object | Objeto que contém os dados da nova configuração do webhook. |
data.id | string | Identificador da configuração de webhook. |
data.name | string | Nome da configuração criada. |
data.context | string | Nome do contexto do evento para o qual a configuração de webhook foi criada. |
data.eventName | string | Nome do evento assinado. |
data.uri | string | URI da API fornecida pelo parceiro para o recebimento dos eventos. |
data.publicKey | string | Chave aleatória gerada pelo parceiro e que será enviada pelo Bankly nos cabeçalhos dos eventos de webhook. |
links | array of objects | Lista de links de próximos estados válidos da entidade/recurso. |
links.url | string | URLs que podem ser utilizadas em um próximo estado da entidade. |
links.rel | string | Descrição de como a URL se relaciona com o recurso atual. |
links.method | string | Tipo de verbo que deve ser utilizado para acessar a URL. |
{
"data": {
"id": "47db4d6b-09ab-4fed-b041-4c8891b37902",
"name": "WEBHOOK_CLIENT",
"context": "Pix",
"eventName": "PIX_CASH_IN_WAS_RECEIVED",
"uri": "https://mywebhookuri/123456",
"publicKey": "MGE4NDIwM2ItNmU5Yi00Zjk0LWE5NmEtNWIwMDdiOGVjMjJj"
},
"links": [
{
"url": "https://api-mtls.sandbox.bankly.com.br/webhooks/47db4d6b-09ab-4fed-b041-4c8891b37902",
"rel": "get_webhook",
"method": "GET"
},
{
"url": "https://api-mtls.sandbox.bankly.com.br/webhooks/47db4d6b-09ab-4fed-b041-4c8891b37902",
"rel": "update_webhook",
"method": "PATCH"
},
{
"url": "https://api-mtls.sandbox.bankly.com.br/webhooks/47db4d6b-09ab-4fed-b041-4c8891b37902",
"rel": "delete_webhook",
"method": "DELETE"
}
]
}
Dica
Para simular uma requisição nesse endpoint, acesse o API Reference.
Erros
Este endpoint pode retornar erros específicos, conforme a tabela a seguir:
Status Code | Código | Mensagem | Descrição |
---|---|---|---|
409 | WEBHOOK_CONFIGURATION_ALREADY_EXISTS | This configuration already exists. | Essa configuração já existe. |
Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints. Portanto, recomendamos a consulta da documentação de erros, onde é possível encontrar as mensagens comuns em inglês que acompanham os erros 400 (se houver).
Updated about 2 months ago