Developer docs

Todo lo necesario para integrar Kapture sin perderse en el camino.

Esta documentacion cubre el recorrido completo: configuracion de la organizacion, contrato del webhook, estructura de payloads, recetas de integracion, matices de arquitectura y operacion en produccion.

HMAC SHA-256 record.created expedient.completed n8n / Make / ERP / CRM

Empezar por quickstart Ver contrato del webhook

Ruta publica principal Webhook org-level firmado

Eventos documentados record.created y expedient.completed

Configuracion organizations/{orgId}

Compatibilidad Legacy user integrations para expedient.completed

Firma `X-Kapture-Signature` sobre el body crudo

Timeout directo 5 segundos en el dispatcher org-level

Campo para dedupe `event` + `id`

Sanitizacion `imageBytes` se elimina del handoff de expediente

Ruta de lectura

Empieza por la pagina correcta

La documentacion esta organizada por la secuencia real de trabajo. Si alguien nuevo entra al proyecto, este es el mejor punto de partida para no saltarse supuestos importantes.

Quickstart

Configuracion minima para dejar un receptor funcionando y verificar la firma en menos de una hora.

Ir al quickstart

Arquitectura

Diferencia entre la via org-level y la via legacy, gatillos reales del backend y puntos de deduplicacion.

Ver arquitectura

Webhooks

Cabeceras, algoritmo de firma, payloads, ejemplos Node/Python y contrato de recepcion.

Abrir referencia

Integraciones

Matriz de decisiones y patrones concretos para n8n, Make, endpoints propios y salidas tabulares.

Ver playbook

Troubleshooting

Sintomas, causas probables y verificaciones concretas cuando la entrega no se comporta como se espera.

Abrir troubleshooting

Despliegue

Como mantener la docs, publicarla en Vercel y replicarla en Hostinger sin tocar la app principal.

Ver despliegue

Modelo actual

Que existe hoy en el backend

El proyecto tiene dos superficies de salida. Entender la diferencia evita confusiones al debuggear entregas o al leer el codigo.

1. Webhook org-level

Es la superficie publica y la que el panel expone hoy. Se configura en la organizacion con `webhookEnabled`, `webhookUrl`, `webhookSecret` y `webhookEvents`.

Eventos

`record.created`, `expedient.completed`

Transporte

POST HTTP directo con firma HMAC y timeout de 5s

Codigo

`WebhookDispatcher.ts` + triggers de Firestore

2. Integraciones legacy por usuario

Se mantienen para compatibilidad y solo participan en `expedient.completed`. Usan Cloud Tasks y un worker HTTP intermedio.

Config

`users/{userId}/integrations/{integrationId}`

Transporte

Cloud Tasks hacia `dispatchWebhook` con envelope propio

Codigo

`TaskQueueService.ts` y `workers/dispatchWebhook.ts`

Journey

Ruta recomendada para un developer nuevo

Si el objetivo es integrar un sistema externo o mantener la salida actual, este orden de lectura reduce mucho el tiempo de orientacion.

1

Lee el quickstart y configura una organizacion. Lo primero es entender donde vive el secret, como se activa el endpoint y que eventos estan disponibles desde el panel.
2

Implementa un receptor que preserve el body crudo. Sin raw body, la verificacion HMAC falla aunque el secret sea correcto.
3

Usa `event + id` como llave de idempotencia. El receptor debe tolerar reintentos y reenvios sin crear duplicados aguas abajo.
4

Prueba `record.created` y `expedient.completed` por separado. No comparten el mismo gatillo interno ni el mismo momento operativo.
5

Revisa la arquitectura antes de asumir retries. `record.created` y la via legacy tienen señales claras en codigo; el path org-level de expediente merece verificacion consciente.
6

Usa troubleshooting como checklist operacional. Ahi estan los sintomas mas comunes: firma rota, eventos que no salen, entregas duplicadas o handoffs parciales.

Codigo fuente

Archivos clave para orientarse en el repo

Estos son los puntos de entrada reales para quien vaya a tocar backend, UI de configuracion o el sitio de documentacion.

backend/functions/src/services/WebhookDispatcher.ts Firma, headers, payload publico y POST directo del webhook org-level.

backend/functions/src/triggers/webhooks.ts Trigger de `record.created` con `failurePolicy: true`.

backend/functions/src/triggers/expedients/onExpedientWrite.ts Produccion de `expedient.completed`, sanitizacion y bifurcacion legacy/org-level.

backend/functions/src/workers/dispatchWebhook.ts Worker HTTP de la via legacy con envelope, custom headers y semantica 4xx/5xx.

web-admin/src/routes/(protected)/settings/organization/general/+page.svelte UI para activar, configurar y previsualizar la integracion saliente por organizacion.

docs-site/ Sitio estatico de documentacion publicado en Hostinger y en Vercel.

Puntos finos

Detalles que conviene saber antes de integrar

Compatibilidad de eventos

Si una organizacion antigua tiene `webhookUrl` y `webhookSecret` pero no `webhookEvents`, el backend resuelve por compatibilidad solo `record.created`.

Respuesta del receptor

El receptor debe responder `2xx` apenas acepte el evento. El procesamiento pesado deberia continuar de forma asincrona del lado receptor.

Payload de expediente

El handoff de `expedient.completed` elimina `imageBytes` antes de salir para evitar mover binarios grandes innecesariamente.

Idempotencia

No asumas entrega exactamente una vez. Usa `event + id` como llave minima de dedupe en el sistema receptor.

Seguir con quickstart Configura el primer receptor y valida la firma extremo a extremo. Ir a arquitectura Entiende como se producen y entregan los eventos dentro del backend.