Pular para o conteúdo principal

Webhooks

Para requests async (toda validation, opcionalmente classification), o DVS entrega resultados via webhooks HTTP POST a um endpoint registrado durante o onboarding. Todo webhook é assinado com HMAC para que seja possível verificar que veio do DVS.

Visão geral​

  1. 1Registro de um endpoint

    Forneça uma URL HTTPS durante o onboarding. A OSIGU a configura no DVS e emite um secret compartilhado.

  2. 2Chamada de uma API async

    POST /v1/classification-requests com mode=async, ou POST /v1/provider-validation-requests. O DVS responde 202 Accepted.

  3. 3O DVS processa em background

    Típico: 3-5s para classification, 15-60s para validation.

  4. 4O DVS faz POST para o endpoint

    Os headers incluem X-DVS-Signature (HMAC), X-DVS-Event-Id, X-DVS-Event-Type. O body é o payload do evento.

  5. 5Verificação da signature e resposta 200

    Em até 10 segundos. Se demorar mais ou retornar não-2xx, o DVS faz retry com backoff.

Tipos de evento​

EventoQuando é emitido
classification.completedA classification foi concluída com sucesso (incluindo type=UNKNOWN).
classification.failedErro técnico durante a classification.
validation.completedA validation foi concluída com um veredito (APPROVED / REJECTED / ERROR).
validation.failedErro técnico durante a validation (extração falhou, indisponibilidade do validator, erro interno).
test.pingEvento sintético de teste enviado sob demanda para verificar a conectividade.

Veja Webhook Events para schemas de payload completos.

Política de retry​

3 tentativas com backoff exponencial: imediata, +60s, +300s. Se as 3 falharem, o evento vai para a dead-letter queue do DVS e é possível consultar o recurso via GET para recuperá-lo.

Após 10 falhas consecutivas no endpoint, o DVS o desativa automaticamente para evitar tráfego descontrolado. A reativação exige ação de admin — contate a OSIGU.

Múltiplos endpoints, filtragem de eventos​

O tenant pode ter N endpoints de webhook registrados (por exemplo, um por ambiente, um por tipo de evento). Cada um pode filtrar por tipos de evento. Veja Implement Webhook Receiver.