Visión general de Webhook Events
Todos los webhooks de DVS comparten un envelope común. Solo el event_type y el contenido de data cambian según el evento.
Envelope
{
"event_id": "evt_550e8400-e29b-41d4-a716-446655440000",
"event_type": "<type>",
"event_version": 1,
"correlation_id": "<uuid>",
"occurred_at": "2026-06-03T17:30:03.000Z",
"data": { /* específico del evento */ }
}
| Campo | Descripción |
|---|---|
event_id | Único por evento padre del delivery attempt (los retries reutilizan el mismo id). Utilizar como idempotency key. |
event_type | Uno de los valores listados a continuación. |
event_version | Versión del schema de data. Actualmente 1. |
correlation_id | UUID que enlaza eventos relacionados. Para classification → validation encadenada, ambos comparten el id de la classification. Para eventos independientes, equivale al id del recurso. |
occurred_at | Timestamp ISO 8601 UTC. |
Catálogo de eventos
classification.completed
La classification finalizó. data.type es uno de los valores del catálogo o UNKNOWN.
classification.failed
La classification no pudo realizarse (caída del engine, fallo de parsing, etc.).
validation.completed
La validation finalizó con un veredicto. data.final_status es APPROVED, REJECTED o ERROR.
validation.failed
La validation falló técnicamente (falló la extracción, caída del validador, error interno).
Además de test.ping, un evento sintético utilizado para verificar conectividad durante el onboarding.
Headers
| Header | Ejemplo |
|---|---|
X-DVS-Signature | t=1748884800,v1=a8d3e8b1c2... |
X-DVS-Signature-Timestamp | 1748884800 |
X-DVS-Event-Id | evt_550e8400-... |
X-DVS-Event-Type | validation.completed |
X-DVS-Event-Version | 1 |
X-DVS-Delivery-Attempt | 1, 2 o 3 |
X-DVS-Correlation-Id | UUID |
Ver Verify HMAC Signatures para conocer cómo validar X-DVS-Signature.