Webhooks

Para requests async (toda validation y, opcionalmente, classification), DVS entrega los resultados vía POST HTTP webhooks a un endpoint que se registra durante el onboarding. Cada webhook va firmado con HMAC para poder verificar que proviene de DVS.

Visión general

1. 1Se registra un endpoint

   Se proporciona una URL HTTPS durante el onboarding. OSIGU la configura en DVS y emite un shared secret.

2. 2Se realiza una llamada async a la API

   POST /v1/classification-requests con mode=async, o POST /v1/provider-validation-requests. DVS responde 202 Accepted.

3. 3DVS procesa en segundo plano

   Tiempos típicos: 3-5s para classification, 15-60s para validation.

4. 4DVS hace POST al endpoint

   Los headers incluyen X-DVS-Signature (HMAC), X-DVS-Event-Id, X-DVS-Event-Type. El body es el payload del evento.

5. 5Se verifica la signature y se responde 200

   Dentro de 10 segundos. Si demora más o devuelve un status no-2xx, DVS reintenta con backoff.

Tipos de evento

Evento	Cuándo se emite
classification.completed	La classification finalizó correctamente (incluyendo type=UNKNOWN).
classification.failed	Error técnico durante la classification.
validation.completed	La validation finalizó con un veredicto (APPROVED / REJECTED / ERROR).
validation.failed	Error técnico durante la validation (falló la extracción, caída del validador, error interno).
test.ping	Evento sintético de prueba enviado bajo demanda para verificar conectividad.

Ver Webhook Events para los schemas completos de los payloads.

Política de retry

3 intentos con backoff exponencial: inmediato, +60s, +300s. Si los 3 fallan, el evento va a la dead-letter queue de DVS y es posible consultar el recurso vía GET para recuperarlo.

Después de 10 fallos consecutivos en el endpoint, DVS lo deshabilita automáticamente para evitar tráfico descontrolado. La reactivación requiere acción de admin — es necesario contactar a OSIGU.

Múltiples endpoints, filtrado de eventos

El tenant puede tener N endpoints de webhook registrados (por ejemplo, uno por ambiente, uno por tipo de evento). Cada uno puede filtrar por tipos de evento. Ver Implement Webhook Receiver.