osFoundry / Platform
Webhooks entrantes
Una URL por app o workspace para recibir eventos. Verificación de firma integrada.
Qué es
Los webhooks entrantes le dan a osFoundry una dirección de recepción para el mundo exterior. Generas un token acotado a una app, una instancia y un canal concretos, y osFoundry te devuelve una URL dedicada bajo /api/v1/webhooks/inbound/{id}. Los sistemas externos (Stripe, GitHub, Zapier, un pipeline de CI, tu propio backend) envían JSON por POST a esa URL, y el evento aterriza en el canal en tiempo real que elegiste, donde tu chat, tus agentes y tus apps pueden actuar sobre él. No hay polling ni un servidor de integración aparte que mantener: el endpoint es la integración.\n\nLa verificación de firma viene incorporada, no añadida por encima. Cada token lleva un secreto de firma HMAC-SHA256, que se muestra una sola vez al generarlo. El emisor calcula una firma sobre el payload y la envía en la cabecera X-OsFoundry-Signature; osFoundry la valida en cada petición y rechaza cualquier cosa sin firmar o alterada en tránsito. Cuando necesitas cambiar la clave de un emisor, rotar el secreto abre una ventana de gracia de 7 días durante la cual el secreto anterior sigue siendo válido, de modo que la rotación nunca descarta un evento en curso. Revocar un token es inmediato: el endpoint empieza a devolver 401 al instante, lo que es la vía rápida ante un secreto filtrado o una integración dada de baja.\n\nComo esto se ejecuta dentro del espacio de trabajo de escritorio BYOK de osFoundry, un evento entrante puede disparar los mismos agentes, apps y conocimiento con los que ya trabajas, sin un impuesto de integración por usuario ni un desvío de tus datos por un intermediario externo. Cada token registra su última hora de uso y su recuento de peticiones de las últimas 24 horas para que veas qué emisores están activos, y la plataforma conserva las últimas 100 peticiones entrantes para reenviarlas, lo que convierte la depuración de webhooks de una conjetura en volver a ejecutar el payload real.
Capacidades principales
- Genera una URL de recepción dedicada por app, instancia y canal: los sistemas externos envían eventos JSON por POST directamente a ese endpoint bajo /api/v1/webhooks/inbound/{id}
- Cada petición se verifica contra una firma HMAC-SHA256 en la cabecera X-OsFoundry-Signature, de modo que los payloads sin firmar o manipulados se rechazan antes de llegar a tu canal
- Rota un secreto de firma con una ventana de gracia de 7 días en la que el secreto antiguo sigue validando, para poder cambiar la clave de los emisores sin perder eventos
- Revoca un token al instante: el endpoint devuelve 401 en el momento de revocarlo, cortando un emisor filtrado o retirado
- Consulta la última hora de uso y el recuento de peticiones de 24 horas por token, y reenvía las últimas 100 peticiones entrantes desde los ajustes del disparador cuando necesites depurar una entrega
Casos de uso
- Desarrollador conectando Stripe: genera un token acotado a un canal de facturación, apunta el webhook de Stripe a la URL y deja que osFoundry rechace cualquier POST cuya firma HMAC no coincida antes de que llegue a un agente
- Ingeniero de operaciones con un secreto filtrado: revoca el token afectado para un 401 inmediato y genera uno nuevo, sin tumbar las demás integraciones que alimentan el espacio de trabajo
- Constructor de automatizaciones conectando un pipeline de CI: envía eventos de estado de build por POST a un canal donde un agente clasifica los fallos, usando el reenvío de las últimas 100 peticiones para depurar la forma del payload
Preguntas frecuentes
¿Cómo verifica osFoundry que un webhook entrante es auténtico?
Cada token entrante tiene un secreto de firma HMAC-SHA256. El emisor calcula una firma sobre el cuerpo de la petición y la envía en la cabecera X-OsFoundry-Signature, y osFoundry la recalcula y la compara en cada petición. Las peticiones con firma ausente o inválida se rechazan, así que solo un sistema que posea el secreto puede publicar en tu canal. El secreto se muestra una sola vez al generar el token: guárdalo en ese momento, porque después no se vuelve a mostrar.
¿Qué pasa con los eventos en curso cuando roto o revoco un token?
La rotación te da una ventana de gracia de 7 días en la que validan tanto el secreto nuevo como el anterior, de modo que puedes actualizar cada emisor sin perder eventos durante el cambio. La revocación es lo opuesto por diseño: el endpoint devuelve 401 de inmediato, cortando al emisor al instante, que es lo que quieres si un secreto se filtra o se retira una integración.
¿Tengo una única URL de webhook para todo, o puedo acotarlas?
Cada token está acotado a una app, una instancia y un canal concretos, y genera su propia URL bajo /api/v1/webhooks/inbound/{id}. Eso significa que un emisor no puede publicar en un canal para el que no tiene permiso, y puedes revocar o rotar una integración concreta sin tocar las demás. Cada token también informa de su última hora de uso y su recuento de peticiones de 24 horas, para que sepas qué endpoints están recibiendo tráfico de verdad.