Openhook

npx add-mcp 'https://openhook.dev/mcp'

Openhook

Una bandeja de entrada de eventos para agentes de IA. Crea una URL pública, espera una devolución de llamada, inspecciona lo que llegó y continúa la tarea.

Openhook opera sus propios servidores de captura HTTP, SMTP y DNS autoritativo. Los eventos viven en su base de datos SQLite. No interviene ningún servicio de webhook externo.

Pruébalo o alójalo

Crea una bandeja de entrada gratuita sin cuenta, o conecta tu agente. El Pro alojado opcional proporciona bandejas de entrada persistentes y recuperación de cuenta; consulta la disponibilidad y planes actuales. El autoalojamiento sigue con licencia MIT sin necesidad de cuenta o suscripción de Openhook.

Recetas prácticas: reenvío local, devoluciones de llamada de GitHub push y devoluciones de llamada de prueba de Stripe.

Primera devolución de llamada en menos de un minuto

Con Python 3 instalado, clona el repositorio y ejecuta el ejemplo desechable:

git clone https://github.com/openhook-dev/openhook-inbox.git
cd openhook-inbox
python3 examples/first_callback.py

Crea una bandeja de entrada gratuita en openhook.dev, envía una devolución de llamada real, verifica los bytes originales y luego elimina su bandeja de entrada y carga útil. El token privado permanece en memoria. No se necesitan cuenta, clave API ni dependencias de Python para este ejemplo. Permanece un metadato mínimo de actividad operativa después de la eliminación.

Instala la habilidad del agente

Para Codex, Claude Code y otros clientes compatibles de Agent Skills:

npx skills add openhook-dev/openhook-inbox --skill openhook

La configuración y permisos de la habilidad explican la conexión MCP, el respaldo REST, el reenvío local y el manejo de tokens privados de bandeja de entrada. Instalar la habilidad no instala ni inicia el servidor.

Ejecútalo

Desde el checkout, instala uv e inicia tu propio servidor:

uv sync
uv run openhook --http

Abre http://127.0.0.1:8788/app.. El sitio web, la API de captura y el endpoint MCP Streamable HTTP comparten un solo servicio y un almacén duradero.

Conecta un cliente MCP a http://127.0.0.1:8788/mcp, o usa uv run openhook para stdio. Un proceso stdio local comparte la misma base de datos con un proceso HTTP en ejecución cuando ambos usan el mismo OPENHOOK_DATABASE. El proceso HTTP debe estar en ejecución para recibir devoluciones de llamada HTTP. Verifica el mismo bucle contra tu servidor con python3 examples/first_callback.py --url http://127.0.0.1:8788. Los proveedores externos necesitan un origen accesible públicamente; el ejemplo de localhost solo demuestra que tu servidor local funciona.

Lanzamientos de GitHub proporcionan código fuente versionado y distribuciones de Python cuando están disponibles. El paquete openhook-mcp no está publicado actualmente en PyPI; usa el checkout del código fuente o un artefacto de lanzamiento en lugar de asumir que una instalación desde el índice de paquetes funciona.

Flujo de trabajo del agente

1. Llama a create_webhook. Guarda el token de gestión privado ohk_.
2. Entrega la URL HTTP pública, dirección de correo electrónico o nombre DNS devuelto al remitente.
3. Llama a wait_for_request con el token de gestión.
4. Inspecciona el evento y actúa. Reconecta usando el cursor next_since devuelto.

Las direcciones de captura públicas no pueden leer ni eliminar eventos. Rota un token de gestión comprometido con rotate_webhook_token. La rotación preserva las direcciones públicas.

Las bandejas de entrada anónimas expiran dentro de siete días. Cada una acepta hasta 1000 eventos retenidos. Cuando está llena, la captura devuelve un error de capacidad en lugar de desalojar eventos aceptados. Los eventos individuales están limitados a 1 MB. Las direcciones de correo electrónico y DNS se devuelven solo cuando sus listeners están configurados.

Herramientas nativas

29 herramientas cubren creación de bandejas de entrada, configuración de respuestas, rotación de tokens, inspección de eventos, búsqueda literal, notas, exportación JSON/CSV, descarga de bytes exactos, esperas HTTP/correo, eventos de prueba, extracción de enlaces/códigos, verificación de devoluciones de llamada, respuestas diferidas, suscripciones de proveedores, eliminación e historial de actividad. Consulta la referencia de herramientas generada.

Historial de actividad duradero

Cada recibo HTTP, correo electrónico y DNS aceptado y cada mutación local exitosa escribe un registro de actividad en la misma transacción que su cambio de estado. Las entregas duplicadas de la fuente también reciben registros. El historial incluye notas, configuraciones de respuesta, respuestas diferidas, rotación de tokens, suscripciones, eliminación y expiración. Léele con get_webhook_activity o haz POST a /api/call con action: activity, el token privado, un cursor since y un limit acotado.

El metadato mínimo de actividad permanece después de la eliminación y expiración de la carga útil. Excluye tokens privados, credenciales de proveedores, cuerpos, notas y secretos de firma. Los eventos existentes se marcan como importados; su historial de mutación anterior no puede reconstruirse. La aplicación agrega registros; esto no es un registro criptográfico a prueba de manipulaciones. Las capturas rechazadas no se almacenan como eventos aceptados.

Configura verification_secret a través de configure_webhook para requerir HMAC SHA256 en cuerpos HTTP sin procesar. Openhook acepta X-Openhook-Signature: sha256=… y el X-Hub-Signature-256 de GitHub. Las firmas inválidas se rechazan antes de la captura. Idempotency-Key y X-GitHub-Delivery deduplican reintentos dentro de una bandeja de entrada.

Las URL entrantes con ?openhook_wait=1 esperan hasta 20 segundos por una respuesta del agente. Inicia respond_to_next_request antes de enviar dicha solicitud.

Configuración

Variable de entorno	Propósito
OPENHOOK_ORIGIN	Origen público, predeterminado http://127.0.0.1:8788
OPENHOOK_DATABASE	Ruta de SQLite, predeterminado data/openhook.sqlite3
OPENHOOK_EMAIL_DOMAIN	Dominio de correo entrante propio; sin configurar desactiva SMTP
OPENHOOK_SMTP_PORT	Listener SMTP, predeterminado 2525; mapea el puerto público 25
OPENHOOK_DNS_DOMAIN	Zona de devolución de llamada delegada propia; sin configurar desactiva DNS
OPENHOOK_DNS_PORT	Listener DNS UDP/TCP, predeterminado 5353; mapea el puerto público 53
OPENHOOK_DNS_ADDRESS	Dirección IPv4 devuelta para consultas DNS A

SMTP rechaza correos para bandejas de entrada desconocidas y nunca retransmite correos. DNS responde solo para la zona configurada y no proporciona recursión.

Despliegue

Usa el Dockerfile y compose.dokploy.yaml en un proyecto Dokploy separado. Adjunta el dominio de Openhook al servicio openhook, puerto 8788. Su volumen de datos nombrado sobrevive a los lanzamientos. Consulta notas de despliegue.

Registro de proveedores y entrega local

Llama a register_github_webhook, register_stripe_webhook o register_linear_webhook para crear una bandeja de entrada nativa y suscribirte en la fuente. Las credenciales de API del proveedor se usan de forma transitoria y nunca se guardan. Las firmas sin procesar se verifican antes de la captura; las marcas de tiempo de Stripe y Linear se verifican para detectar reproducciones. Llama a unregister_webhook antes de que expire la bandeja de entrada para eliminar la suscripción de la fuente.

Para entrega local, configura OPENHOOK_TOKEN con tu token de bandeja de entrada privado y luego ejecuta:

uv run openhook-listen --forward http://127.0.0.1:8080/webhook
# Or wake an already configured local OpenClaw:
uv run openhook-listen --openclaw

La entrega de OpenClaw también requiere OPENCLAW_HOOKS_TOKEN. Sin destino, el listener imprime eventos como JSON. Se conecta hacia afuera a través de HTTPS, guarda un cursor después de la entrega exitosa y reintenta entregas fallidas. La entrega es al menos una vez: los destinatarios deben deduplicar por ID de evento. Cada destino tiene su propio cursor; ejecuta un listener por destino y token. No se incluye el aprovisionamiento de túneles SSH gestionados.

Verificación

El sitio web usa una interfaz de texto centrada y la fuente variable Paper Mono v1.000 autoalojada y el logotipo aprobado de Openhook. Las páginas públicas y los esquemas de herramientas en vivo se renderizan en HTML antes de que se ejecute JavaScript. Los puntos de entrada del agente incluyen /agents.md, /skill.md, /llms.txt, /llms-full.txt, /docs.md y /openapi.json. Su demo de webhook crea una bandeja de entrada, envía una devolución de llamada real y lee el evento capturado. Actualiza las versiones de los assets después de editar web/:

bun run build

uv run --extra dev pytest
node --check web/assets/app.js

Las pruebas ejercitan la captura HTTP nativa, el aislamiento de tokens privados, las verificaciones de firma, la idempotencia, la persistencia, la expiración, MCP y SMTP local real y DNS UDP/TCP.

Con licencia MIT. Los avisos de terceros requeridos están en THIRD_PARTY_NOTICES.md.

Desarrollo alojado y contribuciones

Las cuentas y la facturación están deshabilitadas por defecto. La edición alojada opcional agrega identidad de GitHub, claves de agente revocables, bandejas de entrada propias y derechos verificados de facturas pagadas. Consulta operaciones alojadas para configuración, límites, requisitos de modo de prueba y dependencias de lanzamiento. La presencia de este código no implica ningún comerciante real ni lanzamiento pagado.

Consulta contribuciones y reporte de seguridad.