Webhooks

Webhooks são notificações automáticas que a API envia para uma URL da sua aplicação sempre que um evento relevante acontece, por exemplo, quando uma simulação é concluída ou quando o status de uma operação de crédito muda.

Em vez de a sua aplicação ficar consultando a API repetidamente para saber se algo mudou, é a Grafeno que avisa você no momento em que o evento ocorre.

Isso é especialmente importante nesta API porque várias operações são assíncronas: o resultado da simulação e o retorno da confirmação da operação (sucesso ou erro) chegam por webhook, e não no corpo da resposta da requisição original.

Benefícios

Tempo real: você recebe cada atualização assim que ela acontece, sem atraso.
Sem polling: Elimina a necessidade de consultar a API em loop para verificar mudanças de estado.
Fluxo assíncrono: Resultados de simulação e confirmação são entregues quando ficam prontos.
Rastreabilidade: Cada transição do ciclo de vida da operação gera um evento, permitindo acompanhar toda a jornada do crédito.
Idempotência: Todo evento traz uma idempotency_key, permitindo descartar entregas duplicadas com segurança.

Cadastrando a sua URL de notificação

Para cadastrar a sua URL de notificação, siga os passos abaixo:

Acesse o portal Grafeno Ativos.
No menu lateral esquerdo, clique em Configurações.
Selecione Webhooks.

Na tela de webhooks, preencha os campos abaixo:

Campo	Obrigatório	Descrição
E-mail de contato	Sim	E-mail que receberá informações sobre as notificações, falhas de entrega e demais avisos relacionados ao webhook.
URL de notificação	Sim	Endpoint da sua aplicação que receberá as notificações. Deve ser uma URL válida e servida obrigatoriamente sobre HTTPS.

Exemplo de URL de notificação:

https://api.suaempresa.com.br/webhooks/grafeno

Eventos disponíveis

Por padrão, ao cadastrar a URL, os seguintes eventos passam a ser enviados automaticamente:

Evento	Slug	Descrição
Simulação criada	`simulation-created`	Disparado quando uma nova simulação é criada.
Devedor criado	`debtor-created`	Disparado quando um novo devedor é registrado.
Assinante criado	`subscriber-created`	Disparado quando um novo assinante é criado.
Crédito criado	`credit-created`	Disparado quando um novo crédito é criado.

Evento opcional

Além dos eventos padrão, você pode optar por receber também as atualizações de status de crédito:

Evento	Slug	Descrição
Status do crédito atualizado	`credit-status-updated`	Disparado sempre que o status de um crédito é alterado.

Chave de segurança

Após preencher os campos e clicar em Salvar, o Grafeno gera automaticamente uma Chave de segurança vinculada ao webhook. Essa chave é usada para validar a origem das notificações recebidas, garantindo que a requisição foi realmente enviada pelo Grafeno Ativos e não por terceiros.

📘
Validando a origem das notificações
Recomendamos fortemente que sua aplicação valide a assinatura de cada notificação recebida usando a chave de segurança antes de processar o conteúdo. Consulte o guia de verificação de assinatura do webhook para ver o passo a passo da validação (HMAC-SHA256).

⚠️
URL única
Só é possível cadastrar uma única URL de notificação por conta. Caso precise direcionar os eventos para mais de um destino, faça o roteamento internamente na sua aplicação a partir do endpoint cadastrado.

Estrutura do payload

Todos os eventos seguem o mesmo envelope:

{
  "id": "{id_do_evento}",
  "data": { },
  "event": "credit-status-updated.success",
  "created": "2026-05-19T13:35:52.098Z",
  "api_version": "v2",
  "metadata": {
    "livemode": false,
    "idempotency_key": "{uuid}"
  }
}

Campo	Tipo	Descrição
`id`	`string`	Identificador da notificação.
`data`	`object`	Conteúdo específico do evento (varia conforme o `event`).
`event`	`string`	Nome do evento (ver catálogo abaixo).
`created`	`string` (ISO 8601)	Data/hora em que o evento foi gerado.
`api_version`	`string`	Versão da API que gerou o evento (`v2`).
`metadata.livemode`	`boolean`	`false` em ambiente de teste/staging; `true` em produção.
`metadata.idempotency_key`	`string` (uuid)	Chave única do evento, usada para deduplicação.

📘
Informação
Os eventos seguem a convenção {recurso}-{ação}.{resultado}, onde o resultado é success ou failed.

Catálogo de eventos

`simulation-created.success`

Disparado quando uma simulação é concluída com sucesso. Traz o resultado completo do cálculo (valores, taxas, IOF, CET e o cronograma de parcelas).

Principais campos de data:

Campo	Tipo	Descrição
`credit_id`	`string` (uuid)	Identificador da operação simulada.
`creditor_id`	`string` (uuid)	Identificador do credor.
`liquid_value`	`number`	Valor líquido da operação.
`gross_value`	`number`	Valor bruto da operação.
`buffered_loan_value`	`number`	Valor do empréstimo com encargos embutidos.
`cet`	`number`	Custo Efetivo Total.
`iof` / `daily_iof` / `total_iof`	`number`	Componentes de IOF (base, diário e total).
`monthly_fee`	`number`	Taxa mensal.
`monthly_tir` / `annual_tir`	`number`	TIR mensal e anual.
`tax_percentage`	`number`	Percentual da taxa aplicada.
`total_fee`	`number`	Total de juros/encargos.
`emission_cost` / `emission_tax`	`number` / `string`	Custo e taxa de emissão.
`credit_taxes`	`array`	Detalhamento de tributos/custos por tipo (`commission`, `partner`, `grafeno`, `emission_partner_cost`).
`installments`	`array`	Cronograma de parcelas (ver estrutura abaixo).
`installment_value`	`number`	Valor da parcela calculada.
`installments_quantity`	`integer`	Quantidade de parcelas.
`payments_frequency`	`string`	Periodicidade dos pagamentos.
`contract_date`	`string` (ISO 8601)	Data do contrato.
`calculate_mode`	`string`	Modo de cálculo utilizado.

Estrutura de cada item de installments:

Campo	Tipo	Descrição
`number`	`integer`	Número da parcela.
`due_date`	`string` (ISO 8601)	Data de vencimento.
`day`	`integer`	Dia corrido em relação ao início da operação.
`total_value`	`number`	Valor total da parcela.
`amortization`	`number`	Parcela de amortização do principal.
`interest_value`	`number`	Parcela de juros.
`remaining_balance`	`number`	Saldo devedor após a parcela.
`daily`	`array`	Detalhamento diário (preenchido quando `include_daily_data` é `true`).
`edited_value` / `edited_due_date`	`boolean`	Indicam se valor ou vencimento foram editados manualmente.

`simulation-created.failed`

Disparado quando uma simulação falha em seu processamento devido a ausência ou erro de validação nos dados de envio.

Campo	Tipo	Descrição
`errors`	`string` (uuid)	Mensagens de erro concatenadas.

`debtor-created.success`

Disparado quando o tomador de crédito (devedor) é cadastrado com sucesso.

Campo	Tipo	Descrição
`debtor_id`	`string` (uuid)	Identificador do devedor.
`debtor_status`	`string`	Situação do devedor. Ex.: `active`.

`debtor-created.failed`

Disparado quando o cadastro do tomador de crédito (devedor) falha por alguma validação.

Campo	Tipo	Descrição
`errors`	`string` (uuid)	Mensagens de erro concatenadas.

`credit-created.success`

Disparado quando a confirmação da operação é aceita com sucesso.

Campo	Tipo	Descrição
`credit_id`	`string` (uuid)	Identificador da operação de crédito.
`confirmation_status`	`string`	Situação da confirmação. Ex.: `success`.

`credit-created.failed`

Disparado quando a confirmação da operação falha na validação. As mensagens vêm concatenadas no campo errors, separadas por ;.

Campo	Tipo	Descrição
`errors`	`string`	Mensagens de erro concatenadas.

Exemplos de erros retornados:

Devedor ainda não validado ou inativo.
Minuta obrigatória de determinada categoria (ex.: "Termo de Cessão") não foi fornecida.
Minuta informada ignorada por conter erros ou por não estar associada aos requisitos de minutas da operação.

{
  "id": "0acffc55-4bd1-464b-95c4-3b84c4b356a8",
  "data": {
    "errors": "Debtor is not yet validated or is inactive;Required minute of category \"Termo de Cessão\" does not have a corresponding minute provided;Minute provided with ID 36697e15-2530-4340-a9c8-fedb9a73f6f6 was ignored due to errors or is not associated with any minute requirements for this credit"
  },
  "event": "credit-created.failed",
  "created": "2026-05-19T12:50:54.434Z",
  "api_version": "v2",
  "metadata": {
    "livemode": false,
    "idempotency_key": "bbf0d246-f4f5-4706-b2f3-befd652cf157"
  }
}

`credit-status-updated.success`

Disparado a cada mudança de status da operação de crédito. É o evento que permite acompanhar todo o ciclo de vida.

Campo	Tipo	Descrição
`credit_id`	`string` (uuid)	Identificador da operação.
`old_status`	`string`	Status anterior.
`new_status`	`string`	Novo status.

Ciclo de vida da operação de crédito

Após a confirmação, a operação percorre uma sequência de status até ser liquidada. Cada transição é notificada por um evento credit-status-updated.success.

Status	Descrição
`draft`	Operação simulada e salva como rascunho (`save_as_draft=true`).
`confirmed`	Confirmação aceita; a operação foi efetivada e segue para análise.
`admin_analysis`	Análise de risco realizada pela Grafeno.
`bookkeeper_analysis`	Análise do escriturador.
`banker`	Etapa do bancarizador.
`analyze`	Análise complementar da operação.
`signature`	Operação em processo de assinatura das minutas.
`signed`	Documentos assinados.
`assignment_process`	Processo de cessão do crédito em andamento.
`disbursed`	Recurso desembolsado.
`settled`	Operação liquidada.

Exemplos de notificação

{
  "id": "0acffc55-4bd1-464b-95c4-3b84c4b356a8",
  "data": {
    "cet": 0.9608,
    "iof": 0,
    "cost": 3449.61,
    "cost_tax": 0,
    "credit_id": "44c3659e-6e76-42b6-b6e6-57e214cfc675",
    "daily_iof": 0,
    "total_fee": 29622.03,
    "total_iof": 0,
    "annual_tir": 0.1215,
    "difference": 0,
    "method_tac": "percentage",
    "creditor_id": "9e23cddb-4557-493b-958e-9001c2b9b22b",
    "gross_value": 907790.83,
    "monthly_fee": 0.005,
    "monthly_tir": 0.9608,
    "credit_taxes": [
      {
        "tax": 0,
        "type": "commission",
        "original_amount": 16340.23
      },
      {
        "tax": 0,
        "type": "partner",
        "original_amount": 0
      },
      {
        "tax": 0,
        "type": "grafeno",
        "original_amount": 3449.61
      },
      {
        "tax": 0,
        "type": "emission_partner_cost",
        "original_amount": 3449.61
      }
    ],
    "emission_tax": 0.38,
    "installments": [
      {
        "day": 7,
        "daily": [],
        "number": 1,
        "due_date": "2026-08-12T00:00:00.000Z",
        "total_value": 4538.95,
        "amortization": 0,
        "edited_value": false,
        "interest_value": 4538.95,
        "edited_due_date": false,
        "remaining_balance": 907790.83
      },
      {
        "day": 38,
        "daily": [],
        "number": 2,
        "due_date": "2026-09-12T00:00:00.000Z",
        "total_value": 4538.95,
        "amortization": 0,
        "edited_value": false,
        "interest_value": 4538.95,
        "edited_due_date": false,
        "remaining_balance": 907790.83
      },
      {
        "day": 68,
        "daily": [],
        "number": 3,
        "due_date": "2026-10-12T00:00:00.000Z",
        "total_value": 116041.87,
        "amortization": 111502.92,
        "edited_value": false,
        "interest_value": 4538.95,
        "edited_due_date": false,
        "remaining_balance": 796287.91
      },
      {
        "day": 99,
        "daily": [],
        "number": 4,
        "due_date": "2026-11-12T00:00:00.000Z",
        "total_value": 116041.87,
        "amortization": 112060.43,
        "edited_value": false,
        "interest_value": 3981.44,
        "edited_due_date": false,
        "remaining_balance": 684227.48
      },
      {
        "day": 129,
        "daily": [],
        "number": 5,
        "due_date": "2026-12-12T00:00:00.000Z",
        "total_value": 116041.87,
        "amortization": 112620.73,
        "edited_value": false,
        "interest_value": 3421.14,
        "edited_due_date": false,
        "remaining_balance": 571606.75
      },
      {
        "day": 160,
        "daily": [],
        "number": 6,
        "due_date": "2027-01-12T00:00:00.000Z",
        "total_value": 116041.87,
        "amortization": 113183.84,
        "edited_value": false,
        "interest_value": 2858.03,
        "edited_due_date": false,
        "remaining_balance": 458422.91
      },
      {
        "day": 191,
        "daily": [],
        "number": 7,
        "due_date": "2027-02-12T00:00:00.000Z",
        "total_value": 116041.87,
        "amortization": 113749.76,
        "edited_value": false,
        "interest_value": 2292.11,
        "edited_due_date": false,
        "remaining_balance": 344673.15
      },
      {
        "day": 219,
        "daily": [],
        "number": 8,
        "due_date": "2027-03-12T00:00:00.000Z",
        "total_value": 116041.88,
        "amortization": 114318.51,
        "edited_value": false,
        "interest_value": 1723.37,
        "edited_due_date": false,
        "remaining_balance": 230354.64
      },
      {
        "day": 250,
        "daily": [],
        "number": 9,
        "due_date": "2027-04-12T00:00:00.000Z",
        "total_value": 116041.87,
        "amortization": 114890.1,
        "edited_value": false,
        "interest_value": 1151.77,
        "edited_due_date": false,
        "remaining_balance": 115464.54
      },
      {
        "day": 280,
        "daily": [],
        "number": 10,
        "due_date": "2027-05-12T00:00:00.000Z",
        "total_value": 116041.86,
        "amortization": 115464.54,
        "edited_value": false,
        "interest_value": 577.32,
        "edited_due_date": false,
        "remaining_balance": 0
      }
    ],
    "liquid_value": 888000.99,
    "contract_date": "2026-08-05T18:16:00.000Z",
    "emission_cost": 19789.84,
    "calculate_mode": "tax",
    "commission_tax": 1.8,
    "tax_percentage": 0.5,
    "commission_cost": 16340.23,
    "installment_value": 116041.88,
    "installment_amount": 0,
    "payments_frequency": "monthly",
    "buffered_loan_value": 907790.83,
    "installments_quantity": 10
  },
  "event": "simulation-created.success",
  "created": "2026-07-09T20:19:34.379Z",
  "api_version": "v2",
  "metadata": {
    "livemode": false,
    "idempotency_key": "e0be1b49-d0e1-4ed0-9d03-851d3c88db82"
  }
}

{
  "id": "0acffc55-4bd1-464b-95c4-3b84c4b356a8",
  "data": {
    "errors": "2 erro(s) encontrado(s): contract_date is past the allowed emission date limit, contract_date must be greater or equal than today"
  },
  "event": "simulation-created.failed",
  "created": "2026-07-10T13:17:49.270Z",
  "api_version": "v2",
  "metadata": {
    "livemode": false,
    "idempotency_key": "82b690d7-b7ce-447f-ab22-41eab7ca5746"
  }
}

{
  "id": "0acffc55-4bd1-464b-95c4-3b84c4b356a8",
  "data": {
    "debtor_id": "ff9f5df3-b605-4bbe-bc8f-0c71437f832e",
    "debtor_status": "active"
  },
  "event": "debtor-created.success",
  "created": "2026-07-09T20:41:46.226Z",
  "api_version": "v2",
  "metadata": {
    "livemode": false,
    "idempotency_key": "579bc476-2ac0-4779-9feb-b8b2b55ca88b"
  }
}

{
  "id": "0acffc55-4bd1-464b-95c4-3b84c4b356a8",
  "data": {
    "errors": "5 erro(s) encontrado(s): File debtor_social_or_statute_contract from Debtor 32467466000198 is missing,File debtor_address_proof_file from Debtor 32467466000198 is missing,File debtor_monthly_turnover_on_last_12_months_file from Debtor 32467466000198 is missing,File representative_address_proof_file from Debtor's Representative 25924185800 is missing,File representative_identification_file from Debtor's Representative 25924185800 is missing"
  },
  "event": "debtor-created.failed",
  "created": "2026-07-09T20:29:34.516Z",
  "api_version": "v2",
  "metadata": {
    "livemode": false,
    "idempotency_key": "02c33337-d6ce-498a-b4ce-84a743380b64"
  }
}

{
  "id": "0acffc55-4bd1-464b-95c4-3b84c4b356a8",
  "data": {
    "credit_id": "44c3659e-6e76-42b6-b6e6-57e214cfc675",
    "confirmation_status": "success"
  },
  "event": "credit-created.success",
  "created": "2026-07-09T20:42:06.417Z",
  "api_version": "v2",
  "metadata": {
    "livemode": false,
    "idempotency_key": "208f8e7d-e85b-4c1e-8589-09c81f95735a"
  }
}

{
  "id": "0acffc55-4bd1-464b-95c4-3b84c4b356a8",
  "data": {
    "errors": "Debtor person type (Natural Person) is different from credit person type (Legal Person)"
  },
  "event": "credit-created.failed",
  "created": "2026-07-09T20:25:19.636Z",
  "api_version": "v2",
  "metadata": {
    "livemode": false,
    "idempotency_key": "a167d476-3ca3-4493-a6be-8df372cffe49"
  }
}

{
  "id": "0acffc55-4bd1-464b-95c4-3b84c4b356a8",
  "data": {
    "credit_id": "44c3659e-6e76-42b6-b6e6-57e214cfc675",
    "new_status": "admin_analysis",
    "old_status": "confirmed"
  },
  "event": "credit-status-updated.success",
  "created": "2026-07-09T20:42:06.420Z",
  "api_version": "v2",
  "metadata": {
    "livemode": false,
    "idempotency_key": "67c1f21a-f3cc-466c-b838-db365bbf35c9"
  }
}

Webhooks

Benefícios

Cadastrando a sua URL de notificação

Eventos disponíveis

Evento opcional

Chave de segurança

📘
Validando a origem das notificações

⚠️
URL única

Estrutura do payload

📘
Informação

Catálogo de eventos

`simulation-created.success`

`simulation-created.failed`

`debtor-created.success`

`debtor-created.failed`

`credit-created.success`

`credit-created.failed`

`credit-status-updated.success`

Ciclo de vida da operação de crédito

Exemplos de notificação

Benefícios

Cadastrando a sua URL de notificação

Eventos disponíveis

Evento opcional

Chave de segurança

📘Validando a origem das notificações

⚠️URL única

Estrutura do payload

📘Informação

Catálogo de eventos

simulation-created.success

simulation-created.failed

debtor-created.success

debtor-created.failed

credit-created.success

credit-created.failed

credit-status-updated.success

Ciclo de vida da operação de crédito

Exemplos de notificação

📘
Validando a origem das notificações

⚠️
URL única

📘
Informação

`simulation-created.success`

`simulation-created.failed`

`debtor-created.success`

`debtor-created.failed`

`credit-created.success`

`credit-created.failed`

`credit-status-updated.success`