Webhooks

Receba notificações em tempo real quando o cliente aceitar ou recusar uma proposta.

Visão Geral

Quando o cliente final interagir com a proposta (aceitando ou recusando), a API Parcred Brasil enviará uma notificação POST para a URL de webhook que você informou ao criar a proposta.

Implementação do Endpoint

Seu sistema deve expor um endpoint público (HTTPS) para receber nossas notificações.

Requisitos

Método: POST
Content-Type: application/json
Protocolo: HTTPS (recomendado)
Timeout: Responder em até 10 segundos
Status de sucesso: 200 OK

Payload do Webhook

Exemplo de Payloadjson

{
  "id_proposta_angar": "ANG-d250f450-c920-44fc-ad2b-d4d17e94b5bc",
  "id_proposta_parceiro": "PROP-XYZ-98765",
  "status": "ACEITO",
  "timestamp": "2025-12-12T21:58:36.846Z",
  "detalhes": ""
}

Campos

Campo	Tipo	Descrição
id_proposta_angar	String	ID da proposta no sistema Parcred Brasil
id_proposta_parceiro	String	ID da proposta no seu sistema
status	String	Status final: `ACEITO` ou `RECUSADO`
timestamp	String	Data e hora do evento (ISO 8601)
detalhes	String	Informações adicionais (reservado para uso futuro)

Segurança: Validação da Assinatura

Validação Obrigatória

Para garantir que a requisição veio da Parcred Brasil, cada webhook é assinado usando HMAC-SHA256. A assinatura é enviada no header x-angar-signature. É fundamental que você valide esta assinatura antes de processar o webhook.

A chave secreta (KEY_ANGAR) será fornecida pela equipe Parcred Brasil. Mantenha-a segura e nunca a exponha publicamente.

Função de Validação (Node.js)javascript

const crypto = require("crypto");

function validarAssinatura(req, keyAngar) {
  // 1. Extrair a assinatura recebida do header
  const assinaturaRecebida = req.headers["x-angar-signature"];
  if (!assinaturaRecebida) {
    throw new Error("Header x-angar-signature ausente.");
  }

  // 2. Obter o corpo cru (raw body) da requisição
  const corpoCru = JSON.stringify(req.body);

  // 3. Calcular a assinatura esperada
  const assinaturaCalculada = crypto
    .createHmac("sha256", keyAngar)
    .update(corpoCru)
    .digest("hex");

  // 4. Comparar as assinaturas de forma segura
  const assinaturasCoincidem = crypto.timingSafeEqual(
    Buffer.from(assinaturaRecebida, "hex"),
    Buffer.from(assinaturaCalculada, "hex")
  );

  if (!assinaturasCoincidem) {
    throw new Error("Assinatura inválida.");
  }

  return true;
}

Exemplo Completo de Servidor

Servidor Express (Node.js)javascript

const express = require("express");
const crypto = require("crypto");

const app = express();
app.use(express.json());

const KEY_ANGAR_SECRETA = process.env.KEY_ANGAR_SECRETA;

app.post("/webhook/angar", (req, res) => {
  try {
    // 1. Validar a assinatura
    validarAssinatura(req, KEY_ANGAR_SECRETA);

    // 2. Processar os dados
    const { id_proposta_parceiro, status } = req.body;
    console.log(`Proposta ${id_proposta_parceiro} atualizada para: ${status}`);

    if (status === "ACEITO") {
      // Lógica para aprovar o empréstimo no seu sistema
      aprovarEmprestimo(id_proposta_parceiro);
    } else if (status === "RECUSADO") {
      // Lógica para registrar a recusa
      rejeitarEmprestimo(id_proposta_parceiro);
    }

    // 3. Responder com sucesso
    res.status(200).json({ received: true });

  } catch (error) {
    console.error("Erro ao processar webhook:", error.message);
    res.status(400).json({ error: error.message });
  }
});

function validarAssinatura(req, keyAngar) { /* ... */ }

app.listen(3000, () => {
  console.log("Servidor de webhook rodando na porta 3000");
});

Resposta Esperada

Seu endpoint deve responder com HTTP 200 OK em até 10 segundos. Caso contrário, a API Parcred Brasil poderá considerar a entrega como falha.

200 OKjson

{
  "received": true
}

Tratamento de Erros

Códigos de Status Recomendados

Código	Quando Usar	Retry?
200	Webhook processado com sucesso	Não
400	Erro permanente (assinatura inválida, dados malformados)	Não
500	Erro temporário no seu sistema	Sim
503	Serviço temporariamente indisponível	Sim

Testando seu Webhook

Para testar seu webhook antes de integrar com a API real, você pode usar serviços como:

webhook.site

Serviço gratuito para testes

Gera uma URL temporária que mostra todas as requisições recebidas em tempo real.

Acessar webhook.site →

ngrok

Túnel para localhost

Expõe seu servidor local para a internet, permitindo testar em desenvolvimento.

Acessar ngrok.com →

Próximo Passo

Guia Completo

Veja o fluxo completo de integração com exemplos práticos passo a passo:

Ver Guia Completo