Cadastrar e Gerenciar Webhooks
Antes de iniciar, é necessário saber quais produtos está contratando e se os fluxos possuem notificações via Webhook. Para isso, explicaremos abaixo os produtos disponíveis atualmente neste módulo de APIs e os eventos relacionados:
Context
Este campo será o identificador do produto nas requisições.
Context | Produto |
---|---|
PIX | Pix avulso |
Eventos
Notificações que serão enviadas por produto:
PIX
Entity | Descrição |
---|---|
pix-payment-out | Evento que confirma a realização de pagamentos ou transferências Pix |
pix-payment-in | Evento que informa recebimentos Pix |
pix-reversal-out | Evento que confirma a realização de devoluções de recebimentos Pix |
pix-reversal-in | Evento que informa uma devolução de pagamentos ou transferências Pix |
Cadastrar webhook
Nesta chamada você realizará a definição das rotas que receberão as notificações relacionados aos fluxos.
Passos para integrar
- Realizar autenticação na API - [API Reference]
- Cadastrar Webhook - [API Reference]
Disponibilizamos duas opções de autenticação nas notificações, Basic Auth ou OAuth 2.0. A definição será feita através da requisição, conforme os exemplos abaixo:
Utilizando Basic Authentication:
Neste formato o basic auth definido será enviado nas notificações.
cURL da Chamada
curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/common/v1/webhook/subscription' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data '
{
"context": "PIX",
"entity": "pix-payment-out",
"auth": {
"type": "basic",
"login": "teste",
"pwd": "teste"
},
"webhookUrl": "https://webhookcelcoin/sandbox/event"
}'
Descrição dos campos da chamada
Nome do Campo | Parâmetros | Tipo | Descrição |
---|---|---|---|
context | body | string | Identificador do produto |
entity | body | string | Identificador do Evento. |
webhookUrl | body | string | webhookUrl. |
type | body | string | Tipo de autenticação. basic ou JWT. |
auth | body | objeto | Dados de autenticação do Webhook. |
login | body | string | [BASIC] Login para a autenticação do webhook. |
pwd | body | string | [BASIC] Senha para a autenticação do webhook |
Utilizando OAuth 2.0:
Neste formato de autenticação, será necessário a criação de um endpoint para a geração do JWT. Antes de enviarmos uma notificação solicitaremos o jwt, através das configurações definidas, que serão utilizadas para autenticar na rota destino.
cURL da Chamada
curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/common/v1/webhook/subscription' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data '
{
"entity": "pix-payment-out",
"webhookUrl": "https://webhookcelcoin/sandbox/event",
"auth": {
"type": "jwt",
"urlAuth": "https://authcelcoin/sandbox/token",
"requestType": "body",
"responsePathToken": "access_token",
"requestAuth": [
{
"key": "client_id",
"value": "41b44ab9a56440.teste.celcoinapi.v5",
"type": "string"
},
{
"key": "grant_type",
"value": "client_credentials",
"type": "string"
},
{
"key": "client_secret",
"value": "e9d15cde33024c1494de7480e69b7a18c09d7cd25a8446839b3be82a56a044a3",
"type": "string"
}
]
}
}'
Descrição dos campos da chamada
Nome do Campo | Parâmetros | Tipo | Descrição |
---|---|---|---|
context | body | string | Identificador do produto |
entity | body | string | Identificador do Evento. |
webhookUrl | body | string | Rota para o envio da notificação. |
type | body | string | Tipo de autenticação. basic ou JWT. |
auth | body | objeto | Dados de autenticação do Webhook. |
urlAuth | body | string | Endpoint para a autenticação e geração do jwt. |
requestType | body | string | Estrutura da requisição de autenticação para o seu endpoint |
responsePathToken | body | string | Nome do campo que retornará o jwt. |
requestAuth | body | array | Definição de parâmetros para a autenticação. |
key | body | string | Nome do campo |
value | body | string | Valor do campo |
type | body | string | Tipo do campo |
Exemplo de retorno
Sucesso 200
{
"version": "1.0.0",
"status": "SUCCESS"
}
Error 400
{
"version": "1.0.0",
"status": "ERROR",
"error": {
"errorCode": "CIE999",
"message": "Ocorreu um erro interno durante a chamada da api."
}
}
Consultar cadastros
Neste endpoint será possível localizar os detalhes das rotas cadastradas.
Passos para integrar
- Realizar autenticação na API - [API Reference]
- Consultar Webhooks cadastrados - [API Reference]
cURL da Chamada
curl --location --request GET 'https://sandbox.openfinance.celcoin.dev/common/v1/webhook/subscription?context=PIX&entity=pix-payment-out&active=true' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {{access_token}}'
Descrição dos campos da chamada
Nome do Campo | Parâmetros | Tipo | Descrição |
---|---|---|---|
context | query | string | Identificador do produto |
entity | query | string | Identificador do Evento. |
active | query | Boolean | Situação do cadastro. |
Exemplo de retorno
Sucesso 200
{
"version": "1.0.0",
"status": "SUCCESS",
"body": {
"entity": "string",
"webhookUrl": "string",
"active": true,
"createDate": "2023-03-06T12:02:48.419Z",
"lastUpdateDate": "2023-03-06T12:02:48.419Z",
"auth": {
"login": "string",
"pwd": "string",
"type": "string"
}
}
}
Error 400
{
"version": "1.0.0",
"status": "ERROR",
"error": {
"errorCode": "CIE999",
"message": "Ocorreu um erro interno durante a chamada da api."
}
}
Atualizar/ Editar cadastros
Nesta chamada será possível alterar uma rota, credencial cadastrada ou inativar um evento, utilizando o identificador do cadastro.
Passos para integrar
- Realizar autenticação na API - [API Reference]
- Atualizar Webhook cadastrado - [API Reference]
cURL da Chamada
curl --location --request PUT 'https://sandbox.openfinance.celcoin.dev/common/v1/webhook/subscription/PIX/pix-payment-out' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data '
{
"subscriptionId": "64a340b7987ab1220a72ab66",
"auth": {
"login": "teste",
"pwd": "teste",
"type": "basic"
},
"webhookUrl": "https://webhookcelcoin/sandbox/event",
"active": true
}'
Descrição dos campos da chamada
Nome do Campo | Parâmetros | Tipo | Descrição |
---|---|---|---|
context | path | string | Identificador do produto |
entity | path | string | Identificador do Evento. |
webhookUrl | body | string | webhookUrl. |
type | body | string | Tipo de autenticação. basic ou JWT. |
auth | body | objeto | Dados de autenticação do Webhook. |
login | body | string | [BASIC] Login para a autenticação do webhook. |
pwd | body | string | [BASIC] Senha para a autenticação do webhook |
Exemplo de retorno
Sucesso 200
{
"version": "1.0.0",
"status": "SUCCESS"
}
Error 400
{
"version": "1.0.0",
"status": "ERROR",
"error": {
"errorCode": "CIE999",
"message": "Ocorreu um erro interno durante a chamada da api."
}
}
Excluir cadastros
Está requisão permite excluir uma rota cadastrada para um determinado evento.
Importante
Caso exista mais de uma rota cadastrada para o mesmo evento, será necessário enviar o identificador do cadastro (subscriptionId) como query parameter na requisição.
Passos para integrar
- Realizar autenticação na API - [API Reference]
- Excluir Webhook cadastrado - [API Reference]
cURL da Chamada
curl --location --request DELETE 'https://sandbox.openfinance.celcoin.dev/common/v1/webhook/subscription/PIX/pix-payment-out?subscriptionId=0000001' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {{access_token}}'
Descrição dos campos da chamada
Nome do Campo | Parâmetros | Tipo | Descrição |
---|---|---|---|
context | path | string | Identificador do produto |
entity | path | string | Identificador do evento. |
SubscriptionId | query | string | Identificador do cadastro. |
Exemplo de retorno
Sucesso 200
{
"version": "1.0.0",
"status": "SUCCESS"
}
Error 400
{
"version": "1.0.0",
"status": "ERROR",
"error": {
"errorCode": "CIE999",
"message": "Ocorreu um erro interno durante a chamada da api."
}
}
Tabela de errorCode
Code | Message |
---|---|
CBE205 | Cliente já possui webhook cadastrado com esse evento |
CBE206 | entity é obrigatório. |
CBE207 | webhookUrl é obrigatório e deve ser uma url valida. |
CBE208 | O evento informado não existe. |
CBE209 | Esse tipo de autenticação não está disponível no momento. |
CBE211 | Esse tipo de autenticação não existe. |
CBE212 | auth.login é obrigatório. |
CBE213 | auth.pwd é obrigatório. |
CBE214 | Não é permitido cadastrar esse webhook para Virtual BaaS. |
CBE216 | auth.type é obrigatorio. |
Updated about 1 month ago