Cadastrar e Gerenciar Webhooks

Nossa API 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:

Cadastrar Webhook
Consultar Webhooks cadastrados
Atualizar Webhook
Excluir Webhook

Eventos disponíveis

Para a lista de evento abaixo, utilize o contexto CARTOES .

Evento	Descrição
account-created	Cadastro da Conta para emissão de cartões
card-created	Cartão emitido para uma conta
network-authorization	Status de uma autorização de transação.
card-in-transit	Status do rastreio de um cartão físico.

1. Cadastrar Webhook

Passos para integrar

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

Descrição dos campos da chamada

Nome do Campo	Tipo	Descrição
entity	string	Identificador do Evento.
webhookUrl	string	webhookUrl.
auth	objeto	Dados de autenticação do Webhook.
login	string	Login para Webhook.
pwd	string	Senha para Webhook.
type	string	Tipo de autenticação. Atualmente só está disponível a autenticação basic.

cURL da Chamada

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/common/v1/webhook/subscription' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "context": "CARTOES",
  "entity": "account-created",
  "webhookUrl": "https://www.suaurldewebhook.com",
  "auth": {
    "login": "Seu usuario",
    "pwd": "sua senha",
    "type": "basic"
  }
}'

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 é obrigatorio 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 é obrigatorio.
CBE213	auth.pwd é obrigatorio.
CBE214	Não é permitido cadastrar esse webhook para Virtual BaaS.
CBE216	auth.type é obrigatorio.

2. Consultar Webhooks cadastrados

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?entity=card-in-transit&context=CARTOES' \
--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": "686834b854117d6574d1ce5b",
                "entity": "card-in-transit",
                "context": "CARTOES",
                "webhookUrl": "https://webhook.site/0615cb76-74b7-4390-9b36-5c397fea51",
                "active": true,
                "createDate": "2025-07-04T17:08:24.621Z",
                "lastUpdateDate": "2025-11-25T18:59:21.039Z",
                "auth": {
                    "login": "usuario",
                    "pwd": "senha",
                    "type": "basic",
                    "requestAuth": []
                }
            }
        ]
    },
    "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

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/CARTOES/tracking-updated' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "webhookUrl": "https://webhook-test.com/0274a74eb0d8c8871ec4c87c93d4",
  "auth": {
    "login": "xyz",
    "pwd": "xyz",
    "type": "basic"
  },
  "active": true,
  "subscriptionId": "672f5b20f5eceff25a12"
}'

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."
  }
}

4. Excluir Webhook

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/baas-webhookmanager/v1/webhook/subscription/pix-payment-out?SubscriptionId=64a340b7987ab1220a72ab66' \
--header 'Authorization: Bearer {{token}}'

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."
  }
}

Updated 11 days ago