> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wincred.digital/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> A Wincred envia um POST na sua URL a cada etapa da indicação que você assinou.

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](https://docs.wincred.digital/api-do-parceiro/como-integrar.md#o-que-voce-informa-a-wincred).

## Eventos

| `event_type` | Quando acontece |
| - | - |
| [`term_signed`](https://docs.wincred.digital/api-do-parceiro/eventos/term-signed) | O cliente abriu o link e assinou o termo de autorização |
| [`contract_created`](https://docs.wincred.digital/api-do-parceiro/eventos/contract-created) | O cliente escolheu a proposta e o contrato foi criado. Pode se repetir depois de um reset |
| [`loan_disbursed`](https://docs.wincred.digital/api-do-parceiro/eventos/loan-disbursed) | Proposta averbada e valor desembolsado na conta do cliente (conclusão com sucesso) |
| [`closed`](https://docs.wincred.digital/api-do-parceiro/eventos/closed) | Encerrado sem contratação. Termo vencido não gera notificação |
| [`ping`](https://docs.wincred.digital/api-do-parceiro/eventos/ping) | Apenas no teste, disparado por `POST /webhooks/test` |

## Formato

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

```json theme={null}
{
  "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](https://docs.wincred.digital/api-do-parceiro/assinatura.md) |
| 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`](https://docs.wincred.digital/api-do-parceiro/consultar), 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.

> [!WARNING]
>
> 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](https://docs.wincred.digital/api-do-parceiro/assinatura.md), e não pelo IP de origem.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.