Documentação
DocumentaçãoAPIStatusSuporteFAQscelcoin.com

Cadastrar e Gerenciar Webhooks

Suggest Edits

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.

ContextProduto
PIXPix avulso

Eventos

Notificações que serão enviadas por produto:

PIX

EntityDescrição
pix-payment-outEvento que confirma a realização de pagamentos ou transferências Pix
pix-payment-inEvento que informa recebimentos Pix
pix-reversal-outEvento que confirma a realização de devoluções de recebimentos Pix
pix-reversal-inEvento 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

  1. Realizar autenticação na API - [API Reference]
  2. 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 CampoParâmetrosTipoDescrição
contextbodystringIdentificador do produto
entitybodystringIdentificador do Evento.
webhookUrlbodystringwebhookUrl.
typebodystringTipo de autenticação. basic ou JWT.
authbodyobjetoDados de autenticação do Webhook.
loginbodystring[BASIC] Login para a autenticação do webhook.
pwdbodystring[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 CampoParâmetrosTipoDescrição
contextbodystringIdentificador do produto
entitybodystringIdentificador do Evento.
webhookUrlbodystringRota para o envio da notificação.
typebodystringTipo de autenticação. basic ou JWT.
authbodyobjetoDados de autenticação do Webhook.
urlAuthbodystringEndpoint para a autenticação e geração do jwt.
requestTypebodystringEstrutura da requisição de autenticação para o seu endpoint
responsePathTokenbodystringNome do campo que retornará o jwt.
requestAuthbodyarrayDefinição de parâmetros para a autenticação.
keybodystringNome do campo
valuebodystringValor do campo
typebodystringTipo 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

  1. Realizar autenticação na API - [API Reference]
  2. 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 CampoParâmetrosTipoDescrição
contextquerystringIdentificador do produto
entityquerystringIdentificador do Evento.
activequeryBooleanSituaçã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

  1. Realizar autenticação na API - [API Reference]
  2. 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 CampoParâmetrosTipoDescrição
contextpathstringIdentificador do produto
entitypathstringIdentificador do Evento.
webhookUrlbodystringwebhookUrl.
typebodystringTipo de autenticação. basic ou JWT.
authbodyobjetoDados de autenticação do Webhook.
loginbodystring[BASIC] Login para a autenticação do webhook.
pwdbodystring[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

  1. Realizar autenticação na API - [API Reference]
  2. 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 CampoParâmetrosTipoDescrição
contextpathstringIdentificador do produto
entitypathstringIdentificador do evento.
SubscriptionIdquerystringIdentificador 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

CodeMessage
CBE205Cliente já possui webhook cadastrado com esse evento
CBE206entity é obrigatório.
CBE207webhookUrl é obrigatório e deve ser uma url valida.
CBE208O evento informado não existe.
CBE209Esse tipo de autenticação não está disponível no momento.
CBE211Esse tipo de autenticação não existe.
CBE212auth.login é obrigatório.
CBE213auth.pwd é obrigatório.
CBE214Não é permitido cadastrar esse webhook para Virtual BaaS.
CBE216auth.type é obrigatorio.

Updated 14 days ago