API + Webhooks
Administra el ciclo completo de una inspección via API y recibe eventos mediante webhooks.
Esta guía describe como un sistema backend puede crear, actualizar y procesar inspecciones. Esta es la manera canónica, segura y confiable de integrar Autoinspector en tu sistema.
1. Crear y publicar un template
En el Dashboard, ingresa a Studio y crea el template que vas a consumir por API.
Crea el template desde el Studio de inspecciones.
Agrega assets en distintas secciones (inputs, imágenes, archivos, etc.).
Habilita las validaciones de inteligencia provistas por Autoinspector para ese template.
Define reglas de resultado de inspección según tu lógica de negocio.
Publica el template para que sea consumible por Dashboard y API.
2. Obtener API Key
Usa tu cuenta de developer y copia la clave desde la sección API Keys.
Dentro de Autoinspector Dashboard, accede a configuración de empresa y luego ingresa en Developers.
Copia tu API key de producción desde la sección API Keys.
3. Crear webhook
Sigue los mismos pasos del flujo estándar de creación de webhooks.
Accede al panel de Administración de webhooks.
Haz click en el botón de crear webhook.
Ingresa el endpoint de tu sistema backend. Asegúrate de que sea accesible desde internet.
En la sección de eventos, suscríbete al evento inspection_completed.
Haz click sobre Crear Endpoint.
4. Manejar webhooks de forma segura
Una vez que hayas creado el webhook, debes manejar los eventos que Autoinspector te enviara cuando una inspección sea completada.
En el detalle del webhook creado, vas a ver que Autoinspector te proporciona un webhook signature. Esta signature es necesario para validar la firma del webhook.
De esta forma tu endpoint puede validar que la request que le esta llegando es efectivamente de Autoinspector.
Asegúrate de validar esta firma y payload cuando recibas el evento inspection_completed en tu endpoint.
Importante: usa el contenido crudo de la solicitud
import crypto from 'node:crypto'import express from 'express'const app = express()app.post( '/webhooks/autoinspector', express.raw({ type: 'application/json' }), (req, res) => { const signature = req.header('autoinspector-signature') const secret = process.env.AUTOINSPECTOR_WEBHOOK_SECRET if (!signature || !secret) return res.status(400).json({ error: 'Missing signature or secret' }) const rawBody = req.body const expectedSignature = crypto .createHmac('sha256', secret) .update(rawBody) .digest('hex') const isValid = signature.length === expectedSignature.length && crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(expectedSignature), ) if (!isValid) return res.status(400).json({ error: 'Invalid signature' }) const event = JSON.parse(rawBody.toString('utf8')) if (event.event === 'inspection_completed') { // Tu lógica de negocio } return res.status(200).json({ received: true }) },)5. Obtener contrato para la creación de inspección
Para saber que valores debes enviar en la creacion de una inspección que utilizara la plantilla que acabaste de publicar, debes obtener el contrato de la plantilla.
El contrato de la plantilla es el que define los valores que se pueden enviar en la creación y actualización de una inspección.
Contrato basado en JSON Schema
Puedes obtener este contrato consumiendo el endpoint de obtención de especificación de plantilla:
curl -X GET "https://insurama.api.autoinspector.ai/v2/template/$TEMPLATE_ID?stage=create" \ -H "x-api-key: $AUTOINSPECTOR_API_KEY" \ -H "Content-Type: application/json"6. Crea una inspección
Crea la inspección con el templateId publicado y los assets requeridos para etapa de creación consumiendo el endpoint de creación de inspección:.
curl -X POST "https://insurama.api.autoinspector.ai/v2/inspection" \ -H "x-api-key: $AUTOINSPECTOR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "templateId": "65f8f2c8a4a5b1c2d3e4f5a6", "assets": [ { "identifier": "input_528088f5-e28d-4c2c-adf9-f0f67c4bc28a", "type": "text", "value": "AB123CD" } ], "metadata": { "policy_id": "POL-10021", "external_claim_id": "CLM-92811" } }'7. Iniciar inspección
Toda inspección debe ser iniciada antes de ser completada. El estado de iniciada representa la intención de completitud de la inspección.
Para iniciar una inspección, debes consumir el endpoint de inicio de inspección:
curl -X POST "https://insurama.api.autoinspector.ai/v2/inspection/$INSPECTION_ID/start" \ -H "x-api-key: $AUTOINSPECTOR_API_KEY" \ -H "Content-Type: application/json"8. Enviar declaraciones de assets (opcional)
Si tu template tiene assets que se pueden enviar en la actualización de inspección o necesitas enviar nuevos valores sobre aquellos assets que soportan múltiples instancias (ej: Archivos), puedes hacerlo consumiendo el endpoint de actualización de assets de inspección:
curl -X PATCH "https://insurama.api.autoinspector.ai/v2/inspection/$INSPECTION_ID/assets" \ -H "x-api-key: $AUTOINSPECTOR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "assets": [ { "identifier": "input_d6dae0fb-03c1-47c1-b6a2-d12eda8dbaff", "type": "select", "value": "option_1" } ] }'Subir archivos
En caso de que el valor de asset sea de tipo archivo (image, video, audio o file), primero debes subir el contenido del archivo consumiendo File API.
En la respuesta obtendrás una referencia al archivo subido (_id) que te permitirá hacer referencia al documento en otros endpoints.
curl -X POST "$AUTOINSPECTOR_API_URL/v1/file" \
-H "x-api-key: $AUTOINSPECTOR_API_KEY" \
-F "file=@/ruta/a/tu/document.pdf"Asociar archivo a asset
Para declarar el valor de un asset de tipo archivo, debes hacer uso del _id del archivo subido en el paso anterior:
curl -X PATCH "$AUTOINSPECTOR_API_URL/v2/inspection/$INSPECTION_ID/assets" \
-H "x-api-key: $AUTOINSPECTOR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"assets": [
{
"identifier": "input_12f97833-f738-42bf-8b7e-10b27ae964b9",
"type": "file",
"value": "698110cb0b6620f0f318697c"
}
]
}'9. Finalizar inspección
Completa la inspección para darle cierre y esperar el procesamiento de la misma.
Para finalizar una inspección, debes consumir el endpoint de finalización de inspección:
curl -X POST "https://insurama.api.autoinspector.ai/v2/inspection/$INSPECTION_ID/finish" \ -H "x-api-key: $AUTOINSPECTOR_API_KEY" \ -H "Content-Type: application/json"10. Verificar entrega de webhooks
Revisa el estado de entrega y los logs del endpoint para confirmar que recibiste y procesaste inspection_completed.
Accede al panel de Administración de webhooks.
Haz click sobre el webhook que creaste.
Revisa la tabla Historial y verifica que exista un registro de solicitud hacia tu endpoint con código de respuesta satisfactorio (2xx).