Webhooks

Para manter o seu sistema atualizado de forma reativa, a Wincred envia requisições POST (webhooks) para a URL que você cadastrou a cada etapa da indicação que você assinou. Você implementa e mantém o endpoint; a Wincred assina cada envio para que você possa verificar a origem.

Cadastro

O cadastro é feito com o time de integrações, durante o onboarding, e não pela API. Você informa a URL HTTPS, a forma de autenticação (apenas a assinatura, ou a assinatura combinada com um header seu) e os eventos que quer receber. A Wincred gera o segredo da assinatura e o entrega a você. Veja Como integrar.

Eventos

`event_type`	Quando acontece
`term_signed`	O cliente abriu o link e assinou o termo de autorização
`contract_created`	O cliente escolheu a proposta e o contrato foi criado. Pode se repetir depois de um reset
`loan_disbursed`	Proposta averbada e valor desembolsado na conta do cliente (conclusão com sucesso)
`closed`	Encerrado sem contratação. Termo vencido não gera notificação
`ping`	Apenas no teste, disparado por `POST /webhooks/test`

Formato

POST <sua webhook_url>
Content-Type: application/json
X-Wincred-Event-Id: 7d0f3a6e-2b1c-4d5e-8f90-1a2b3c4d5e6f
X-Wincred-Signature: t=1791000000,v1=<hex>

{
  "event_id": "7d0f3a6e-2b1c-4d5e-8f90-1a2b3c4d5e6f",
  "event_type": "contract_created",
  "occurred_at": "2026-10-06T08:00:00-03:00",
  "data": {
    "process_external_id": "2f1d4c8e-6a7b-4e3f-9c0d-1a2b3c4d5e6f",
    "hub_code": "padrao",
    "status": "contract_created",
    "proposal": { "gross_amount": "5000.00", "installments": 24 },
    "ccb_number": "1234"
  }
}

Header	Conteúdo
`Content-Type`	`application/json`
`X-Wincred-Event-Id`	Igual ao `event_id` do corpo
`X-Wincred-Signature`	`t=<epoch>,v1=<hex>`. Veja Assinatura do webhook
Seu header de autenticação	Apenas se você optou por um header próprio no cadastro

Campo	Conteúdo
`event_id`	Identificador único da notificação. Use-o para deduplicar
`event_type`	O evento
`occurred_at`	Instante da mudança de status, em RFC 3339 com fuso de São Paulo
`data`	A visão do processo, com a mesma estrutura do `GET`, congelada no momento em que a notificação foi gravada

Por privacidade, nenhuma notificação traz dado pessoal do cliente.

Resposta e retentativas

Sua resposta	O que a Wincred faz
2xx	Considera entregue. O corpo da sua resposta é ignorado
Timeout, erro de rede ou de TLS, `408`, `429`, `5xx`	Retenta a cada 5 minutos, até 6 vezes (cerca de 30 minutos no total)
Outros `4xx` (inclusive `401` e `403`) e qualquer `3xx`	Encerra a notificação, sem retentativa. A Wincred não segue redirecionamentos

Recomendamos validar a assinatura, persistir o evento em uma fila para processamento assíncrono e retornar 2xx imediatamente. Assim, o processamento mais demorado do seu lado não compete com o prazo de resposta do webhook.

Se o seu endpoint ficar indisponível por mais de cerca de 30 minutos, as retentativas das notificações do período se esgotam. Depois de uma indisponibilidade, reconcilie o estado consultando o GET dos processos em andamento e avise o time de integrações.

Pelo menos uma vez, sem ordem garantida

A mesma notificação pode chegar mais de uma vez. Guarde os event_id já processados e ignore os repetidos, respondendo 2xx para eles.
Não há garantia de ordem entre notificações. Ordene por occurred_at e, para o estado atual, consulte o GET.

Origem das notificações

A Wincred não garante IP fixo de saída para os webhooks. Por isso, valide cada notificação pela assinatura, e não pelo IP de origem.

Introdução

Guia de integração

Referência da API

Eventos

Cadastro

Eventos

Formato

Resposta e retentativas

Pelo menos uma vez, sem ordem garantida

Origem das notificações