InstitucionalBlogService DeskStatus Page

Registro de um novo webhook

stable

Suggest Edits

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

Requisição HTTP

POST 'https://api-mtls.sandbox.bankly.com.br/webhooks/configurations' \

curl --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:

ScopeDescrição
webhook.writeConcede acesso para criar ou atualizar um webhook.

Cabeçalhos (Headers)

NomeDescrição
api-versionObrigatório. Versão da API. Atualmente estamos na versão 1.0.
AuthorizationObrigató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:

NomeTipoDescrição
uristringObrigatório. URI da API fornecida pelo parceiro para o recebimento dos eventos. Exemplo: https://meuwebhook/123456.
privateKeystringObrigató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.
publicKeystringObrigató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
namestringObrigatório. Nome que o assinante deseja dar para identificar o evento. Esse nome é da escolha do parceiro. Exemplo: TED_CASH_IN.
eventNamestringObrigatório. Nome do evento que está sendo assinado. Ele deve ser escrito exatamente conforme apresentamos na documentação de eventos.
contextstringObrigató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 a publicKey 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 uma privateKey e uma publicKey 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:

NomeTipoDescrição
dataobjectObjeto que contém os dados da nova configuração do webhook.
data.idstringIdentificador da configuração de webhook.
data.namestringNome da configuração criada.
data.contextstringNome do contexto do evento para o qual a configuração de webhook foi criada.
data.eventNamestringNome do evento assinado.
data.uristringURI da API fornecida pelo parceiro para o recebimento dos eventos.
data.publicKeystringChave aleatória gerada pelo parceiro e que será enviada pelo Bankly nos cabeçalhos dos eventos de webhook.
linksarray of objectsLista de links de próximos estados válidos da entidade/recurso.
links.urlstringURLs que podem ser utilizadas em um próximo estado da entidade.
links.relstringDescrição de como a URL se relaciona com o recurso atual.
links.methodstringTipo 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 CodeCódigoMensagemDescrição
409WEBHOOK_CONFIGURATION_ALREADY_EXISTSThis 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