Webhooks

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

Como Funciona

Você registra uma URL de callback
Quando um evento ocorre, enviamos um POST para sua URL
Você responde com HTTP 200 para confirmar recebimento
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

{
  "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:

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:

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

Responda rápido

Retorne 200 em menos de 5 segundos. Processe o evento de forma assíncrona.

Idempotência

Webhooks podem ser reenviados. Use o webhook_id para deduplicar.

Valide a assinatura

Sempre verifique o X-Zipdin-Signature antes de processar.

Trate falhas

Se sua URL falhar 3x seguidas, o webhook será desativado automaticamente.

Começando

Conceitos

Webhooks

Webhooks

Como Funciona

Eventos Disponíveis

Payload do Webhook

Validando a Autenticidade

Configuração

Boas Práticas

Responda rápido

Idempotência

Valide a assinatura

Trate falhas

​Webhooks

​Como Funciona

​Eventos Disponíveis

​Payload do Webhook

​Validando a Autenticidade

​Configuração

​Boas Práticas

Responda rápido

Idempotência

Valide a assinatura

Trate falhas

Webhooks

Como Funciona

Eventos Disponíveis

Payload do Webhook

Validando a Autenticidade

Configuração

Boas Práticas