Índice de páginas

Resumo

O Webhook é disparado automaticamente sempre que ocorre uma mudança de status em uma requisição de antecipação.

Para garantir a segurança da integração, todas as notificações enviadas incluem uma assinatura HMAC no cabeçalho da requisição. Essa assinatura é gerada a partir de uma chave secreta compartilhada entre os sistemas, permitindo que o receptor valide a autenticidade e a integridade da mensagem recebida.

As credenciais necessárias para gerar e validar a assinatura são específicas para cada ambiente (staging e production) e podem ser obtidas no Watchtower, na aba Desenvolvedores. É essencial manter essa chave segura e renovar periodicamente quando necessário.

Visão Geral dos Endpoints

[POST] /register_webhook

Este endpoint permite registrar uma nova URL de Webhook associada à sua organização. Uma vez registrada, todas as mudanças de status das requisições de antecipação serão notificadas para o endpoint configurado.

**[GET] /**get_webhook

Este endpoint retorna a URL do webhook atualmente configurado para a organização, juntamente com metadados como status, data de criação e última atualização. É útil para verificar se o webhook está ativo e corretamente cadastrado.

[DELETE] /delete_webhook

Este endpoint remove o webhook cadastrado. Após a exclusão, nenhuma notificação será enviada até que um novo webhook seja registrado.

[GET] /generate_webhook_secret

Este endpoint gera um segredo HMAC que deve ser usado para assinar e validar as notificações enviadas pelo Webhook. Ele garante a integridade e autenticidade das mensagens recebidas pelo seu sistema.

Integração via HMAC (assinatura da mensagem)

As notificações de Webhook são assinadas com HMAC-SHA256 usando um segredo exclusivo da sua organização. O objetivo é permitir que você valide se o payload foi enviado pela CoreAI e não sofreu alterações.

Como funciona

Gere o segredo HMAC

Obtenha o segredo via endpoint: [GET] /webhook/generate_webhook_secret. Armazene-o de forma segura (ex.: Secret Manager).

Receba o webhook

Seu endpoint receberá o evento com os cabeçalhos de autenticação + o cabeçalho de assinatura:

x-signature: sha256=<assinatura_hex>

Exemplo:

x-signature: sha256=5d5e48a4bbaed0929ac1a429fcaf513d818068bd2ba4df7d6b3180ca3d8be8ae

Recalcule a assinatura

No seu servidor, calcule:
```
assinatura_local = hex( HMAC_SHA256(chave_secreta, corpo_bruto_da_requisicao) )
```
Importante: use o corpo bruto (raw body) exatamente como recebido na requisição, sem reformatar/serializar novamente.
Compare (tempo constante)

Compare assinatura_local com o valor do header x-signature (após remover o prefixo sha256=), usando comparação tempo-constante para evitar ataques de timing.
Responda

Em caso de sucesso, responda 2xx. Em caso de falha (4xx ou 5xx) vamos reenviar depois de [1m, 5m, 30, 2h, 6h, 12h, 24h], sempre referente ao primeiro disparo.

Payloads

De acordo com o status da solicitação, um payload será enviado à URL cadastrada, conforme abaixo:

Requested: 
{
	"contract_anticipation_request_id":"9fba92a4-f4fb-402a-8f18-199d001336c1",
	"installment_amount":3000,
	"advance_amount":2727.28,
	"rate":0.1,
	"advance_periods":1,
	"advance_initial_date":"2025-08-27",
	"status":"requested"
}

Approved:
{
	"contract_anticipation_request_id":"9fba92a4-f4fb-402a-8f18-199d001336c1",
	"status":"approved"
}

Sent:
{
	"contract_anticipation_request_id":"9fba92a4-f4fb-402a-8f18-199d001336c1",
	"status":"sent"
}

Pcs:
{
	"contract_anticipation_request_id":"9fba92a4-f4fb-402a-8f18-199d001336c1",
	"status":"pcs"
}

Signed:
{
	"contract_anticipation_request_id":"9fba92a4-f4fb-402a-8f18-199d001336c1",
	"status":"signed"
}

Ada:
{
	"contract_anticipation_request_id":"9fba92a4-f4fb-402a-8f18-199d001336c1",
	"installment_amount":3000,
	"advance_amount":2727.28,
	"rate":0.1,
	"advance_periods":1,
	"advance_initial_date":"2025-08-27",
	"status":"ada"
}

Disbursed:
{
	"contract_anticipation_request_id":"9fba92a4-f4fb-402a-8f18-199d001336c1",
	"installment_amount":3000,
	"advance_amount":2727.28,
	"rate":0.1,
	"advance_periods":1,
	"advance_initial_date":"2025-08-27",
	"disbursed_at":"2025-08-27T22:45:31.028759",
	"status":"disbursed"
}

Completed:
{
	"contract_anticipation_request_id":"9fba92a4-f4fb-402a-8f18-199d001336c1",
	"status":"completed"
}

Canceled:
{
	"contract_anticipation_request_id":"9fba92a4-f4fb-402a-8f18-199d001336c1",
	"status":"canceled"
}

Rejected:
{
	"contract_anticipation_request_id":"9fba92a4-f4fb-402a-8f18-199d001336c1",
	"status":"rejected"
}