Webhooks

Várias etapas do crédito são assíncronas (consulta de margem, assinatura, averbação, desembolso). Em vez de ficar consultando o recurso em loop (polling), cadastre URLs e a Socinal avisa você quando cada evento concluir.

Cadastrando um endpoint

Registre a URL e os eventos


curl -X POST https://api.socinal.com.br/v1/webhooks \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://seu-sistema.com.br/webhooks/socinal",
    "eventos": ["autorizacao.confirmada", "assinatura.concluida", "averbacao.concluida", "desembolso.liquidado"]
  }'

Guarde o `secret`


{
  "id": "wh_a1b2...",
  "url": "https://seu-sistema.com.br/webhooks/socinal",
  "eventos": ["autorizacao.confirmada", "assinatura.concluida", "averbacao.concluida", "desembolso.liquidado"],
  "secret": "whsec_abc123...",
  "ativo": true,
  "criado_em": "2026-06-27T12:00:00Z"
}

O secret é exibido só uma vez — ele é a chave para validar a assinatura das entregas.

Eventos disponíveis

Evento	Dispara quando
`autorizacao.confirmada`	O trabalhador aceitou a autorização (via API ou pelo link web)
`margem.concluida`	A consulta de margem terminou
`margem.falhou`	A consulta de margem falhou
`assinatura.concluida`	A assinatura foi concluída
`averbacao.concluida`	A averbação foi registrada
`averbacao.falhou`	A averbação falhou
`desembolso.liquidado`	O PIX foi liquidado
`desembolso.falhou`	O desembolso falhou

Validando a assinatura

Cada entrega vem assinada com HMAC-SHA256 no header X-Webhook-Signature: sha256=<hex>. Calcule o HMAC do corpo cru da requisição usando o seu secret e compare:


import { createHmac, timingSafeEqual } from 'node:crypto';
 
function assinaturaValida(corpoCru: string, header: string, secret: string) {
  const esperado = createHmac('sha256', secret).update(corpoCru).digest('hex');
  const recebido = header.replace('sha256=', '');
  return timingSafeEqual(Buffer.from(esperado), Buffer.from(recebido));
}

Valide a assinatura antes de processar o payload, e responda 200 rapidamente — faça o processamento pesado em segundo plano. Entregas sem 200 são reenviadas com backoff.

Webhooks vs. polling

Prefira webhooks para resultados assíncronos. Use as consultas (GET /v1/emprestimos/{id}, GET /v1/emprestimos/{id}/averbacao) como fallback — por exemplo, para reconciliar caso você tenha perdido uma entrega.