Cadastrar e Gerenciar Webhooks

Nossa API de BaaS possui o modulo de Gerenciamento de Webhook, com esses serviços você consegue administrar suas rotas de Webhook sem precisar acionar o time da Celcoin, esse modulo contempla os seguintes serviços:

• 1. Cadastrar Webhook
• 2. Consultar Webhooks cadastrados
• 3. Atualizar Webhook
• 4. Excluir Webhook

🚧

Importante

Informamos que, para garantir a estabilidade e previsibilidade das integrações, nunca removeremos campos de um contrato de webhook sem uma comunicação prévia aos clientes. No entanto, novos campos poderão ser adicionados conforme necessário para aprimorar as funcionalidades e o valor dos dados fornecidos. Recomendamos que nossos cliente evite restringir a entrada de webhooks com novos campos, assegurando que o sistema esteja preparado para receber essas atualizações e manter a compatibilidade contínua.

🚧

Importante

Nosso webhook é uma ferramenta transacional, projetada para notificar eventos específicos em tempo real. Ele não deve ser utilizado como base para a construção de extratos próprios pelo cliente. A fonte oficial e confiável para consulta de extratos é o extrato gerado pela Celcoin. O uso indevido do webhook para essa finalidade pode levar a inconsistências nos dados.

Confira o tutorial desse módulo

Eventos disponíveis.

Onboarding

KYC V1 (Descontinuado)

Transferência entre contas (P2P)

Pix

Pix Automático

Portabilidade e reivindicação de chave Pix

TED

Cobranças Avulsas (Geração de boleto)

Pagamento de contas

Recargas

Recebimento de liquidações do arranjo de cartões via SLC (Domicílio Bancario)

Bloqueios Judiciais

Lançamentos Manuais - Tesouraria

No ambiente de homologação, os eventos entrycredit e entrydebit estão disponíveis para uso pelos clientes com o objetivo de realizar testes e validar integrações com o sistema de movimentações financeiras.

📘

Os eventos pix-infraction e pix-med-refund deverão ser cadastrados por meio do Webhook Manager.

1. Cadastrar Webhook

O cadastro de webhooks permite configurar quais eventos serão recebidos e em qual rota (URL) esses eventos deverão ser enviados.

Passos para integrar

1. Realizar autenticação na API - [API Reference]
2. Cadastrar Webhook - [API Reference]

A requisição pode utilizar:

• Request Basic, ou Request JWT

Descrição dos campos da chamada - Basic

JSON da chamada

{
  "entity": "pix-payment-out",
  "webhookUrl": "https://www.celcoin.com.br/baas",
  "auth": {
    "login": "string",
    "pwd": "string",
    "type": "basic"
  }
}

cURL da Chamada

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/baas/v2/webhook/subscription' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "entity": "pix-payment-out",
  "webhookUrl": "https://www.celcoin.com.br/baas",
  "auth": {
    "login": "string",
    "pwd": "string",
    "type": "basic"
  }
}'

Descrição dos campos da chamada - JWT

JSON da chamada

{
  "entity": "pix-payment-out",
  "webhookUrl": "https://webhook.d3fkon1.com/639f9618-f378-4e09-9f17-df1b46663429",
  "auth": {
    "responsePathToken": "access_token",
    "requestType": "body",
    "urlAuth": "www.test.com.br",
    "requestAuth":[
      {
        "key":"user",
        "value":"nomeUsuario",
        "type":"string"
      },
       {
        "key":"password",
        "value":"senha",
        "type":"string"
      }
    ]
    "type": "jwt"
  }
}

Exemplo de retorno

👍

Sucesso 200

{
    "body": {
        "subscriptionId": "684b45a5391dbba43a367f80"
    },
    "status": "SUCCESS",
    "version": "1.0.0"
}

❗

Error 400

{
  "version": "1.0.0",
  "status": "ERROR",
  "error": {
    "errorCode": "CIE999",
    "message": "Ocorreu um erro interno durante a chamada da api."
  }
}

Tabela de errorCode

2. Consultar Webhooks cadastrados

A consulta de webhooks permite obter a lista de webhooks previamente cadastrados.

Passos para integrar

1. Realizar autenticação na API - [API Reference]
2. Consultar Webhooks cadastrados - [API Reference]

• O endpoint aceita o parâmetro evento como query parameter. Exemplo: onboarding-create
• Caso o parâmetro não seja informado, serão retornados todos os webhooks cadastrados.

cURL da Chamada

curl --location --request GET 'https://sandbox.openfinance.celcoin.dev/baas/v2/webhook/subscription' \
--header 'Authorization: Bearer {{token}}'

Você pode buscar um status especifico utilizando os seguintes parâmetros:

Entity -> Identificador do Evento.
Active -> true ou false

Exemplo de retorno

👍

Sucesso 200

{
    "body": {
        "subscriptions": [
            {
                "subscriptionId": "6778399a82f0238d133fae0c",
                "entity": "pix-payment-in",
                "webhookUrl": "https://kubernetes-prod.celcoin.dev/sandbox-baas-validation-webhook/validate/webhook",
                "active": true,
                "createDate": "2024-11-27T09:19:41.693Z",
                "lastUpdateDate":"2023-03-06T12:02:48.419Z",
                "auth": {
      						"login": "string",
      						"pwd": "string",
      						"type": "string"
          	 }
        ]
    },
    "status": "SUCCESS",
    "version": "1.0.0"
}

❗

Error 400

{
  "version": "1.0.0",
  "status": "ERROR",
  "error": {
    "errorCode": "CIE999",
    "message": "Ocorreu um erro interno durante a chamada da api."
  }
}

3. Atualizar Webhook

A atualização de webhooks permite modificar informações relacionadas a um evento e à rota (URL) configurada.

Passos para integrar

1. Realizar autenticação na API - [API Reference]
2. Atualizar Webhook cadastrado - [API Reference]

Para clientes que possuem mais de uma rota configurada para o mesmo evento, é obrigatório informar o subscriptionId na requisição, a fim de identificar qual configuração deve ser atualizada.

Descrição dos campos da chamada

JSON da chamada

{
  "webhookUrl": "https://webhook.d3fkon1.com/61a254bd-a833-476c-8d8f-c625ecc40534",
  "auth": {
    "login": "string",
    "pwd": "string",
    "type": "basic"
  }
}

cURL da Chamada

curl --location --request PUT 'https://sandbox.openfinance.celcoin.dev/baas/v2/webhook/subscription/pix-payment-out' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "webhookUrl": "string",
  "auth": {
    "login": "login",
    "pwd": "password",
    "type": "basic"
  },
  "active": true,
  "subscriptionId": "64a340b7987ab1220a72ab66"
}'

Exemplo de retorno

👍

Sucesso 200

{
    "body": {
        "subscriptionId": "684b45a5391dbba43a367f80"
    },
    "status": "SUCCESS",
    "version": "1.0.0"
}

❗

Error 400

{
    "status": "ERROR",
    "error": {
        "errorCode": "CBE205",
        "message": "Cliente já possui webhook cadastrado com esse evento."
    },
    "version": "1.0.0"
}

4. Excluir Webhook

A exclusão de webhooks permite remover configurações previamente cadastradas para um evento.

Passos para integrar

1. Realizar autenticação na API - [API Reference]
2. Excluir Webhook cadastrado - [API Reference]

Para clientes que possuem mais de uma rota configurada para o mesmo evento, é obrigatório informar o subscriptionId no query parameter para identificar qual configuração deve ser excluída.

cURL da Chamada

curl --location --request DELETE 'https://sandbox.openfinance.celcoin.dev/baas/v2/webhook/subscription/pix-payment-out?SubscriptionId=64a340b7987ab1220a72ab66' \
--header 'Authorization: Bearer {{token}}'

Exemplo de retorno

👍

Sucesso 200

{
  "version": "1.0.0",
  "status": "SUCCESS"
}

❗

Error 400

{
    "status": "ERROR",
    "error": {
        "errorCode": "CBE205",
        "message": "Cliente já possui webhook cadastrado com esse evento."
    },
    "version": "1.0.0"
}