Register and Manage 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 | Product |
|---|---|
| PIX | Pix e Pix Indireto Avulso |
| INVOICE-NFSE | Issuance of Service Invoice |
| BAASPAY | Credenciamento Contas BaaS na Sub Celcoin |
| SPB | SPB e SLC |
Events
Notificações que serão enviadas por produto:
Pix / Pix Indireto
| Entity | Description |
|---|---|
| pix-payment-out | Event that confirms the completion of Pix payments or transfers |
| pix-payment-in | Event that informs Pix receipts |
| pix-reversal-out | Event confirming the return of Pix receipts |
| pix-reversal-in | Event that informs a return of Pix payments or transfers |
Indirect Pix
| Entity | Description |
|---|---|
| pix-dict-claim | Event that informs the process of portability and reclaiming a Pix key |
| pix-infraction | Event that informs receipt of Pix violations |
| pix-med-refund | Event that confirms the return via MED |
Automatic Pix
| Event | Description |
|---|---|
| pix-automatic-recurrency-awaiting-debtor | Evento disparado quando o pagador recebe a solicitação de recorrência. |
| pix-automatic-recurrency-completed | Evento disparado quando pagador aceita ou recusa a recorrência. |
| pix-automatic-payment-instruction-cashin | Evento enviado tanto para casos de recebimento no dia do vencimento, quanto para casos onde o recebimento ocorreu em uma das 3 retentativas de recebimento após o vencimento. |
| pix-automatic-payment-instruction-expired | Evento com o resultado da retentativa de recebimento. |
| pix-automatic-payment-instruction-completed | Evento com o resultado de recebimento. |
| pix-automatic-payment-instruction-cancelled | Evento de Cancelamento de Agendamento |
Issuance of Service Invoice
| Entity | Description |
|---|---|
| invoice-nfse-registration | Evento que atualiza status da solicitação de Emissão da NFs-e e retorna dados da nota fiscal. |
| invoice-nfse-cancellation | Evento que atualiza status da solicitação de cancelamento da NFs-e |
Credenciar Contas BaaS na Sub Celcoin
| Entity | Description |
|---|---|
| account-accreditation | Evento que atualiza o status do credenciamento das contas do BaaS na Sub Celcoin |
Credenciar Contas BaaS na Sub Celcoin
| Entity | Description |
|---|---|
| spb-event-error | Esse evento ocorre quando uma liquidação padrão não é efetivada |
Important
Please be advised that, to ensure the stability and predictability of integrations, we will never remove fields from a webhook contract without prior communication to customers. However, new fields may be added as needed to enhance the functionality and value of the data provided. We recommend that our customers avoid restricting the entry of webhooks with new fields, ensuring that the system is prepared to receive these updates and maintain ongoing compatibility.
Register webhook
In this connection, you will define the routes that will receive notifications related to the flows.
Passos para integrar
- Perform API authentication - [ API Reference ]
- Cadastrar Webhook - [API Reference]
We offer two authentication options for notifications, Basic Auth or OAuth 2.0. The definition will be made through the request, as per the examples below:
Utilizando Basic Authentication:
In this format the defined basic auth will be sent in notifications.
cURL Call
JSON
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" }'
Description of call fields
| Field Name | Parameters | Type | Description |
|---|---|---|---|
| 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 | object | Webhook authentication data. |
| 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 Call
JSON
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" } ] } }'
Description of call fields
| Field Name | Parameters | Type | Description |
|---|---|---|---|
| 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 | object | Webhook authentication data. |
| 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 (body, form-data, x-www-form-urlencoded) |
| 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 | Field name |
| value | body | string | Valor do campo |
| type | body | string | Tipo do campo |
Return example
Success 200
JSON
{ "version": "1.0.0", "status": "SUCCESS" }
Error 400
JSON
{ "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
- Perform API authentication - [ API Reference ]
- View registered Webhooks - [ API Reference ]
cURL Call
JSON
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}}'
Description of call fields
| Field Name | Parameters | Type | Description |
|---|---|---|---|
| context | query | string | Identificador do produto |
| entity | query | string | Identificador do Evento. |
| active | query | Boolean | Situação do cadastro. |
Return example
Success 200
JSON
{ "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
JSON
{ "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
- Perform API authentication - [ API Reference ]
- Update registered Webhook - [ API Reference ]
cURL Call
JSON
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 }'
Description of call fields
| Field Name | Parameters | Type | Description |
|---|---|---|---|
| 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 | object | Webhook authentication data. |
| login | body | string | [BASIC] Login para a autenticação do webhook. |
| pwd | body | string | [BASIC] Senha para a autenticação do webhook |
Return example
Success 200
JSON
{ "version": "1.0.0", "status": "SUCCESS" }
Error 400
JSON
{ "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.
Important
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
- Perform API authentication - [ API Reference ]
- Delete registered Webhook - [ API Reference ]
cURL Call
JSON
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}}'
Description of call fields
| Field Name | Parameters | Type | Description |
|---|---|---|---|
| context | path | string | Identificador do produto |
| entity | path | string | Identificador do evento. |
| SubscriptionId | query | string | Identificador do cadastro. |
Return example
Success 200
JSON
{ "version": "1.0.0", "status": "SUCCESS" }
Error 400
JSON
{ "version": "1.0.0", "status": "ERROR", "error": { "errorCode": "CIE999", "message": "Ocorreu um erro interno durante a chamada da api." } }
errorCode table
| Code | Message |
|---|---|
| CBE205 | Client already has a webhook registered with this event |
| CBE206 | entity is required. |
| CBE207 | webhookUrl é obrigatório e deve ser uma url valida. |
| CBE208 | The reported event does not exist. |
| CBE209 | This type of authentication is not currently available. |
| CBE211 | This type of authentication does not exist. |
| CBE212 | auth.login é obrigatório. |
| CBE213 | auth.pwd é obrigatório. |
| CBE214 | It is not allowed to register this webhook for Virtual BaaS. |
| CBE216 | auth.type é obrigatorio. |