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

# Webhooks

> Receba notificações em tempo real sobre eventos nas propostas

# Webhooks

Webhooks permitem que sua aplicação receba notificações HTTP em tempo real quando eventos ocorrem na plataforma Zipdin.

## Como Funciona

```mermaid theme={null}
sequenceDiagram
    participant Z as Zipdin
    participant S as Seu Servidor
    Z->>S: POST /seu-webhook (evento)
    S->>Z: 200 OK
    Note over Z,S: Se falhar, Zipdin reenvia até 3x
```

1. Você registra uma URL de callback
2. Quando um evento ocorre, enviamos um POST para sua URL
3. Você responde com HTTP 200 para confirmar recebimento
4. Se não recebemos 200, reenviamos até **3 tentativas** com backoff

## Eventos Disponíveis

| Evento                   | Descrição                      | Etapa        |
| ------------------------ | ------------------------------ | ------------ |
| `proposta.criada`        | Nova proposta criada           | Proposta     |
| `proposta.pre_aprovada`  | Análise de crédito aprovada    | Proposta     |
| `proposta.aprovada`      | Proposta aprovada              | Proposta     |
| `proposta.negada`        | Proposta negada                | Proposta     |
| `proposta.cancelada`     | Proposta cancelada             | Proposta     |
| `averbacao.solicitada`   | Averbação enviada à conveniada | Averbação    |
| `averbacao.aprovada`     | Margem reservada com sucesso   | Averbação    |
| `averbacao.negada`       | Conveniada negou averbação     | Averbação    |
| `formalizacao.iniciada`  | Link de assinatura enviado     | Formalização |
| `formalizacao.concluida` | Documentos assinados           | Formalização |
| `efetivacao.concluida`   | Contrato registrado            | Efetivação   |
| `pagamento.realizado`    | Valor liberado ao cliente      | Pagamento    |
| `pagamento.falha`        | Falha no pagamento             | Pagamento    |

## Payload do Webhook

```json theme={null}
{
  "evento": "proposta.aprovada",
  "timestamp": "2026-08-06T14:30:00-03:00",
  "dados": {
    "nu_proposta": 789456,
    "nu_cpf": "12345678901",
    "st_proposta": "aprovada",
    "vl_emprestimo": 10000.00,
    "no_conveniada": "Empresa ABC"
  },
  "metadata": {
    "tentativa": 1,
    "webhook_id": "wh_abc123"
  }
}
```

## Validando a Autenticidade

Cada webhook inclui um header `X-Zipdin-Signature` com HMAC-SHA256 do body:

```python theme={null}
import hmac
import hashlib

def validar_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)
```

## Configuração

Registre sua URL de webhook via API ou painel:

```bash theme={null}
curl -X POST https://api.zipdin.com.br/api/v1/webhooks \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seuapp.com/webhooks/zipdin",
    "eventos": ["proposta.aprovada", "pagamento.realizado"],
    "secret": "seu_secret_para_validacao"
  }'
```

## Boas Práticas

<CardGroup cols={2}>
  <Card title="Responda rápido" icon="bolt">
    Retorne 200 em menos de 5 segundos. Processe o evento de forma assíncrona.
  </Card>

  <Card title="Idempotência" icon="rotate">
    Webhooks podem ser reenviados. Use o `webhook_id` para deduplicar.
  </Card>

  <Card title="Valide a assinatura" icon="shield">
    Sempre verifique o `X-Zipdin-Signature` antes de processar.
  </Card>

  <Card title="Trate falhas" icon="triangle-exclamation">
    Se sua URL falhar 3x seguidas, o webhook será desativado automaticamente.
  </Card>
</CardGroup>