Webhooks

Endpoints para que otros sistemas avisen a ur de que hay documentos nuevos o cambiados, en vez de esperar al siguiente escaneo programado.

No usan el access token

Los webhooks quedan fuera de la autenticación normal de /api/*: quien llama es un sistema externo que no puede llevar tu token. Cada uno tiene su propio secreto, generado al configurar la fuente de ficheros en el panel.

Tampoco aparecen en /api/openapi.json.

Comparten un límite de 20 peticiones por minuto y por IP.

Avisar de URLs nuevas (fuente web)

El útil para integrar: si tienes una fuente de ficheros de tipo web, puedes empujarle URLs desde tu CMS cuando publiques o actualices una página, en vez de esperar al rastreo.

curl -X POST https://ur.tuempresa.com/api/webhooks/web/<id-de-la-file-source> \
  -H "Authorization: Bearer <secreto-del-webhook>" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://tusitio.com/blog/articulo-nuevo"]}'

{ "ok": true, "accepted": 1, "queued": true }

Campo	Significado
accepted	Cuántas URLs se aceptaron tras filtrar
queued	Si se encoló un escaneo

El secreto es el del webhook de esa fuente, no un access token — lo encuentras en la configuración de la file source en el panel.

Solo se aceptan URLs http y https

Cualquier otra cosa se descarta en silencio. Si accepted sale más bajo de lo que mandaste, revisa el esquema de las URLs.

Devuelve 404 si ese identificador no corresponde a una fuente de tipo web.

Notificaciones de Google Drive

POST /api/webhooks/drive

Este no lo llamas tú: lo llama Google cuando cambia algo en la carpeta vigilada, si has configurado la suscripción de notificaciones al dar de alta la fuente de Drive.

Se autentica con las cabeceras que manda Google (X-Goog-Channel-ID, X-Goog-Channel-Token, X-Goog-Resource-State), contrastadas contra el secreto guardado en la fuente. Si el canal no se reconoce, responde 200 de todas formas — es la forma de decirle a Google que deje de reintentar sobre una suscripción que ya no existe.

Los avisos se agrupan en ventanas de 10 segundos, para que una ráfaga de cambios no dispare docenas de escaneos.

Lo único que necesitas saber como integrador es que si las notificaciones están configuradas, los cambios en Drive se recogen solos, sin esperar a la frecuencia de escaneo.

Comprobar que llegó

Los webhooks encolan trabajo; no indexan de forma síncrona. Para saber si un documento concreto ya está disponible, consulta su estado:

curl "https://ur.tuempresa.com/api/inferences/<inferencia>/file-sources/<file-source>?file=<ruta>" \
  -H "Authorization: Bearer $UR_TOKEN"

Ver Estado de un fichero concreto.