Webhooks

Recibir resultados automáticamente

En lugar de consultar una operación mediante polling, podés configurar una URL para que Clasificar te envíe una notificación cuando el resultado esté disponible.

V1, V2 y Cuenta → Webhook comparten una configuración por cuenta y ambiente, con destinos independientes para Sandbox y Producción. Habilitá el webhook antes de que termine la operación que querés recibir.

Configurar un webhook

Usá GET /v2/webhooks/config para consultar la configuración y PATCH /v2/webhooks/config para definir o actualizar el destino. La configuración también se administra desde /v1/webhooks/config o Cuenta → Webhook; cambiar la URL, el secreto o la activación afecta a ambas versiones en ese ambiente. La URL debe ser HTTPS y accesible públicamente.

Configurar un webhook
Campo	Tipo	Descripción
url	string \| null	URL de destino, hasta 2048 caracteres. Usá null para quitarla, junto con enabled: false si estaba habilitada.
enabled	boolean	Habilita o deshabilita el webhook. Para habilitarlo necesitás una URL.
rotateSecret	boolean	Con true genera un nuevo secreto de firma.

Terminal

curl -X PATCH 'https://api.clasific.ar/v2/webhooks/config' \
  -H 'x-api-key: <TU_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://tu-dominio.example/webhooks/clasificar","enabled":true}'

Todos los campos del PATCH son opcionales. Los valores omitidos se conservan.

GET y PATCH devuelven url, enabled y secret. El secreto está disponible cada vez que consultás la configuración; no se muestra sólo al crearlo.

Usá secret para verificar las firmas. Guardalo de forma segura en tu servidor y no lo expongas en el frontend. Si lo rotás, las entregas posteriores se firman con el nuevo secreto, incluidos los reintentos.

Eventos

Las operaciones asincrónicas generan eventos cuando terminan. Las consultas de vehículo que se resuelven de forma inmediata no generan estos eventos.

Eventos
Evento	Cuándo se envía
modules.completed	Una operación de módulos termina como completed o partial.
modules.failed	Una operación de módulos termina como failed.
vehicle.completed	Una búsqueda asincrónica de vehículo termina correctamente.
vehicle.failed	Una búsqueda asincrónica de vehículo termina como failed.
webhook.test	Solicitás un evento de prueba.

Una operación modular con estado partial llega mediante modules.completed. Revisá siempre data.status y el estado de cada módulo.

Payload

Payload
Campo	Descripción
id	ID del evento. Usalo para reconocer duplicados.
type	Tipo de evento, por ejemplo modules.completed.
apiVersion	Versión de la API: v2.
createdAt	Fecha y hora del evento en formato ISO.
data	En eventos de operación, la misma representación de la operación que obtenés mediante polling. En webhook.test contiene un mensaje de prueba.

JSON

{
  "id": "evt_7c62755f-6270-47b1-9c08-503e3e44bcf4",
  "type": "modules.completed",
  "apiVersion": "v2",
  "createdAt": "2026-09-06T12:00:00.000Z",
  "data": {
    "id": "op_92cff723-014a-4b1a-aa26-82bb5287e6aa",
    "kind": "modules",
    "status": "completed",
    "plate": "ZZ000ZZ",
    "modules": {
      "gnc": {
        "status": "completed",
        "data": {
          "total": 0,
          "items": []
        },
        "error": null
      }
    },
    "createdAt": "2026-09-06T12:00:00.000Z",
    "updatedAt": "2026-09-06T12:00:00.000Z"
  }
}

Reintentos y duplicados

Las entregas pueden repetirse (at-least-once). En algunos casos podés recibir el mismo evento más de una vez: usá payload.id para deduplicarlo y evitar procesarlo de nuevo.

Respondé con cualquier status HTTP 2xx para confirmar la entrega.

Si tu endpoint no responde correctamente, Clasificar vuelve a intentar hasta un máximo de 5 intentos en total, incluido el primero. Al agotar los intentos, la entrega queda como failed.

Verificar la firma

Verificá la firma antes de procesar cada webhook. Usá el secreto de la configuración y estos headers:

Verificar la firma
Header	Descripción
x-clasificar-signature	Firma HMAC-SHA256, con formato v1=<hex>.
x-clasificar-timestamp	Timestamp Unix en segundos, enviado como texto y utilizado para calcular la firma.
x-clasificar-event	Tipo de evento con prefijo v2., por ejemplo v2.modules.completed. En payload.type el valor es modules.completed.
x-clasificar-delivery	ID de la entrega, sin el prefijo evt_ del ID de evento.

La firma se calcula sobre el timestamp, un punto y el body exacto recibido, codificados en UTF-8. No vuelvas a serializar el JSON antes de verificarlo.

TEXT

signedPayload = timestamp + "." + rawBody
hex = HMAC-SHA256(secret, signedPayload).hex
expectedSignature = "v1=" + hex

Compará expectedSignature con x-clasificar-signature usando una comparación de tiempo constante. Usá el texto de x-clasificar-timestamp tal como lo recibiste.

El prefijo v1= identifica la versión del formato de firma, no la versión de la API. El payload sigue teniendo apiVersion: "v2".

Historial de entregas

Consultá GET /v2/webhooks/deliveries para revisar entregas recientes de V1 y V2 en el ambiente actual y diagnosticar problemas. La respuesta contiene deliveries, limit y offset.

Historial de entregas
Parámetro	Valores	Por defecto
limit	Entero de 1 a 100	25
offset	Entero de 0 a 10000	0

Datos de referencia
Campo de entrega	Descripción
id	Identificador de la entrega.
event	Tipo de evento. Los eventos V2 se muestran sin el prefijo v2. del header.
apiVersion	Versión que originó el evento: v1 o v2. El payload conserva el formato de esa versión.
status	pending: pendiente o esperando reintento; processed: confirmada con 2xx; failed: agotó los intentos.
attempts	Cantidad de intentos realizados.
responseStatus	Último código HTTP recibido; puede ser null si no hubo respuesta.
nextAttemptAt	Fecha prevista para el próximo intento. Revisá status para saber si sigue pendiente.
createdAt	Fecha de creación de la entrega.
payload	Contenido del evento enviado.

El estado de una entrega indica si tu endpoint la recibió; no es el estado de la operación.

Probar la configuración

Usá POST /v2/webhooks/test para enviar un evento webhook.test a la URL configurada. Requiere una URL y el webhook habilitado; no necesita body.

Terminal

curl -X POST 'https://api.clasific.ar/v2/webhooks/test' \
  -H 'x-api-key: <TU_API_KEY>'

Recibís HTTP 202 con la entrega pendiente:

JSON

{
  "id": "7c62755f-6270-47b1-9c08-503e3e44bcf4",
  "status": "pending"
}

Consultá el historial para comprobar si tu endpoint confirmó la recepción.

Configurar, consultar y probar webhooks no consume consultas de patente ni de módulos. Estas requests sí están sujetas al rate limit de tu cuenta.

Referencia de API →

Buscar documentación

Documentación