Webhooks

Webhooks são a forma recomendada de acompanhar o ciclo de vida de uma proposta sem ficar consultando a API repetidamente (polling). Em vez de perguntar “e agora?”, sua aplicação registra uma URL e a Zipdin a notifica por HTTP assim que cada evento acontece — da criação da proposta ao pagamento liberado. Esta página cobre o fluxo de entrega e reenvio, o catálogo de eventos por etapa, o formato do payload, como validar a autenticidade das notificações e as boas práticas para um endpoint confiável.

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.

Primeiros passos

Conceitos

E-Consignado

Marketplace

Novidades

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

​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

Como Funciona

Eventos Disponíveis

Payload do Webhook

Validando a Autenticidade

Configuração

Boas Práticas