Webhook

A Plataforma de Crédito utiliza webhooks para notificar o originador sobre eventos assíncronos da esteira de crédito. Todos os eventos são enviados para uma URL cadastrada, e o tipo do evento é identificado pelo campo type ou event no corpo da notificação.

Atualmente é possível cadastrar uma única URL de webhook para receber todos os eventos gerais da esteira de crédito (Webhook padrão). Se o produto a ser implementando for de consignado privado é possível cadastrar uma 2ª URL exclusivamente para os eventos de "garantias".

Tipos de webhook

Existem dois tipos de webhook na plataforma, com finalidades distintas:

Tipo	Finalidade	Ativação
Webhook padrão	Receber eventos gerais da esteira de crédito (`APPLICATION_STATUS_UPDATED`, `PERSON_DOCUMENT_STATUS_UPDATED`, `BUSINESS_DOCUMENT_STATUS_UPDATED`)	Cadastro via API pelo próprio originador
Webhook de Garantias	Receber eventos assíncronos de consulta de margem consignável (`GuaranteeAuthorizationRequest`, `GuaranteeAuthorizationUpdate`, `GuaranteeBalanceUpdate`)	Habilitação pela Celcoin mediante solicitação

Originadores que operam com crédito consignado devem solicitar ao seu Gerente de Conta Celcoin a habilitação do serviço de Garantias no webhook. Sem essa habilitação, os eventos assíncronos de autorização e consulta de margem não serão disparados.

Gerenciamento do Webhook

Cadastrar webhook

POST /banking/originator/webhooks

Registra a URL que receberá as notificações de eventos da plataforma.

Headers

Header	Obrigatório	Descrição
`Authorization`	Sim	`Bearer <token>`
`Content-Type`	Sim	`application/json`

Body

Campo	Tipo	Obrigatório	Descrição
`url`	string	Sim	URL do endpoint receptor das notificações
`headers`	object	Não	Headers customizados enviados em toda notificação. Utilizado para autenticação estática no receptor

Exemplo — cadastro simples

curl --request POST \
  'https://sandbox.platform.flowfinance.com.br/banking/originator/webhooks' \
  --header 'Authorization: Bearer <seu_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://webhook-test.com/fdc925c66b298967bbe8b12a65decfff"
  }'

Exemplo — cadastro com chave estática

Para proteger o endpoint receptor, é possível cadastrar um header de autenticação estático. A plataforma enviará esse header em todas as notificações, permitindo que o receptor valide a origem da requisição.

curl --request POST \
  'https://sandbox.platform.flowfinance.com.br/banking/originator/webhooks' \
  --header 'Authorization: Bearer <seu_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://webhook-test.com/fdc925c66b298967bbe8b12a65decfff",
    "headers": {
        "x-api-key": "some-key"
    }
  }'

O campo headers aceita o padrão x-api-key. O valor informado será enviado como header em cada notificação disparada para a URL cadastrada.

Resposta (HTTP 201)

{
  "id": "2636ba56-d82e-4f14-951d-3b7936b68439",
  "url": "https://webhook-test.com/fdc925c66b298967bbe8b12a65decfff",
  "created_at": "2025-07-29T20:56:43.496152Z",
  "updated_at": "2025-07-29T20:56:43.496152Z",
  "version": 1
}

Listar webhooks cadastrados

GET /banking/originator/webhooks

Retorna os webhooks cadastrados para o originador.

Headers

Header	Obrigatório	Descrição
`Authorization`	Sim	`Bearer <token>`

Exemplo

curl --request GET \
  'https://sandbox.platform.flowfinance.com.br/banking/originator/webhooks' \
  --header 'Authorization: Bearer <seu_token>'

Resposta (HTTP 200)

[
  {
    "id": "2636ba56-d82e-4f14-951d-3b7936b68439",
    "url": "https://api.celcoin.com.br/webhook/celcoin/clt",
    "created_at": "2025-07-29T20:56:43.496152Z",
    "updated_at": "2025-07-29T21:04:21.436823Z",
    "version": 1
  }
]

Atualizar webhook

PUT /banking/originator/webhooks/{webhook_id}

Atualiza a URL ou os headers de um webhook existente.

Path parameter

Parâmetro	Tipo	Descrição
`webhook_id`	UUID	Identificador do webhook a ser atualizado

Exemplo

curl --request PUT \
  'https://sandbox.platform.flowfinance.com.br/banking/originator/webhooks/2636ba56-d82e-4f14-951d-3b7936b68439' \
  --header 'Authorization: Bearer <seu_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://api.celcoin.com.br/webhook/celcoin/clt"
  }'

Resposta (HTTP 200)

{
  "id": "2636ba56-d82e-4f14-951d-3b7936b68439",
  "url": "https://api.celcoin.com.br/webhook/celcoin/clt",
  "created_at": "2025-07-29T20:56:43.496152Z",
  "updated_at": "2025-07-29T21:04:21.436823Z",
  "version": 1
}

Deletar webhook

DELETE /banking/originator/webhooks/{webhook_id}

Remove um webhook cadastrado.

Path parameter

Parâmetro	Tipo	Descrição
`webhook_id`	UUID	Identificador do webhook a ser removido

Exemplo

curl --request DELETE \
  'https://sandbox.platform.flowfinance.com.br/banking/originator/webhooks/2636ba56-d82e-4f14-951d-3b7936b68439' \
  --header 'Authorization: Bearer <seu_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://www.dominio.com/webhooks"
  }'

Resposta (HTTP 204)

⚠️
**Em caso de falha no recebimento de algum webhook não temos um processo de retentativa ou reenvio de um evento de webhook. Se ocorrer esse cenário será necessário realizar uma consulta de forma ativa nas APIs necessárias.