MCP lets free-code call out to external tools. Inbound webhooks are the opposite direction: an external system — a Flowise flow, a CI job, a GitHub event — makes an HTTP POST to free-code, and that event either lands in a queue the agent can read or wakes the agent to act on it immediately.

1. You register a named hook (for example flowise) from inside free-code.
2. free-code exposes it at POST http://127.0.0.1:<port>/hook/<name> and returns a secret.
3. You configure the external system (Flowise, GitHub, …) to POST to that URL with the secret.
4. When a request arrives and passes authentication, the event is delivered to the agent.

Each hook has a delivery mode:

1 · Direction — the reverse of MCP

2 · Lifecycle — from registration to the agent

3 · Delivery — what happens to each event

• Let a Flowise flow drive the agent — a flow's HTTP node calls back into free-code when it finishes.
• React to CI/CD — a failed build POSTs its log and the agent starts investigating.
• Bridge SaaS events — GitHub, Stripe, or any service that emits webhooks (via a tunnel, see below).
• Collect asynchronous callbacks — kick off long-running external work, then wait_for_webhook_event for the result.
• Register the callback for you — the agent can POST free-code's URL into the external system's own API.

With the /webhook command (CLI)

# Register a hook that wakes the agent on every event
/webhook add flowise --trigger

# Show its callback URL + secret again
/webhook url flowise

# List hooks and server status
/webhook list

# Peek at buffered events (queue mode)
/webhook events

# Force a specific port for this session
/webhook port 8790

# Remove a hook
/webhook rm flowise

Omit --trigger to create a queue hook. A secret is generated automatically.

By asking the agent (works everywhere, including the plugin)

The same actions are exposed as tools, so in the CLI, the IDE plugin, or the desktop app you can just say: "register a webhook called flowise in trigger mode and give me the URL."

After /webhook add test --trigger, take the URL and secret it printed, then:

# Replace the port and secret with what /webhook url test showed
curl -X POST http://127.0.0.1:8788/hook/test \
  -H 'content-type: application/json' \
  -H 'X-Webhook-Secret: <your-secret>' \
  -d '{"msg":"hello from curl"}'

Expected: the request returns {"ok":true}, and in a trigger hook the agent wakes and reacts to the payload.

For a queue hook, drain what arrived:

/webhook events        # or ask the agent to poll the webhook events

Auth is mandatory — a wrong or missing secret is rejected with 401:

curl -i -X POST http://127.0.0.1:8788/hook/test \
  -H 'X-Webhook-Secret: wrong' -d '{}'
# HTTP/1.1 401 Unauthorized

There's also a liveness endpoint:

curl http://127.0.0.1:8788/health
# {"ok":true,"hooks":["test"]}

• Binds 127.0.0.1 by default — not reachable from the network.
• Every hook requires a credential. A hook with no secret never authenticates.
• Shared secret — send it in the X-Webhook-Secret header (compared in constant time).
• HMAC — set an hmacSecret and sign the raw body: X-Signature: sha256=<hex>.
• Body size is capped (1 MB by default) to reject oversized payloads.

Each session binds the first free port from 8787 upward (8787, 8788, 8789, …), so several free-code windows coexist without clashing. The callback URL always reflects the port a session actually bound — check it with /webhook url <name>.

To pin a known port:

# Per session, live:
/webhook port 8790

# Or set it before launch:
FREECODE_WEBHOOK_PORT=8790 free-code

Tools

Config file — ~/.free-code/agent/webhook-receiver.json

{
  "enabled": true,
  "host": "127.0.0.1",
  "port": 8787,
  "portRange": 20,
  "publicBaseUrl": null,
  "defaultMode": "queue",
  "maxBodyBytes": 1048576,
  "hooks": {
    "flowise": { "mode": "trigger", "secret": "…" }
  }
}

Environment overrides

MCP permite que free-code llame hacia afuera a herramientas externas. Los webhooks entrantes son la dirección opuesta: un sistema externo — un flujo de Flowise, un job de CI, un evento de GitHub — hace un POST HTTP a free-code, y ese evento o bien llega a una cola que el agente puede leer, o despierta al agente para que actúe sobre él de inmediato.

1. Registras un hook con nombre (por ejemplo flowise) desde dentro de free-code.
2. free-code lo expone en POST http://127.0.0.1:<port>/hook/<name> y devuelve un secreto.
3. Configuras el sistema externo (Flowise, GitHub, …) para hacer POST a esa URL con el secreto.
4. Cuando llega una solicitud y pasa la autenticación, el evento se entrega al agente.

Cada hook tiene un modo de entrega:

1 · Dirección — lo inverso de MCP

2 · Ciclo de vida — del registro al agente

3 · Entrega — qué le pasa a cada evento

• Dejar que un flujo de Flowise conduzca al agente — el nodo HTTP de un flujo llama de vuelta a free-code cuando termina.
• Reaccionar a CI/CD — un build fallido hace POST de su log y el agente empieza a investigar.
• Conectar eventos de SaaS — GitHub, Stripe, o cualquier servicio que emita webhooks (mediante un túnel, ver abajo).
• Recolectar callbacks asíncronos — inicia un trabajo externo de larga duración, luego usa wait_for_webhook_event para el resultado.
• Registrar el callback por ti — el agente puede hacer POST de la URL de free-code hacia la propia API del sistema externo.

Con el comando /webhook (CLI)

# Registra un hook que despierta al agente en cada evento
/webhook add flowise --trigger

# Muestra de nuevo su URL de callback + secreto
/webhook url flowise

# Lista los hooks y el estado del servidor
/webhook list

# Revisa los eventos en búfer (modo queue)
/webhook events

# Fuerza un puerto específico para esta sesión
/webhook port 8790

# Elimina un hook
/webhook rm flowise

Omite --trigger para crear un hook queue. Se genera un secreto automáticamente.

Pidiéndoselo al agente (funciona en todas partes, incluido el plugin)

Las mismas acciones se exponen como herramientas, así que en el CLI, el plugin del IDE, o la aplicación de escritorio puedes simplemente decir: "registra un webhook llamado flowise en modo trigger y dame la URL."

Después de /webhook add test --trigger, toma la URL y el secreto que imprimió, luego:

# Reemplaza el puerto y el secreto con lo que mostró /webhook url test
curl -X POST http://127.0.0.1:8788/hook/test \
  -H 'content-type: application/json' \
  -H 'X-Webhook-Secret: <your-secret>' \
  -d '{"msg":"hello from curl"}'

Esperado: la solicitud devuelve {"ok":true}, y en un hook trigger el agente despierta y reacciona al payload.

Para un hook queue, consume lo que llegó:

/webhook events        # o pídele al agente que consulte los eventos del webhook

La autenticación es obligatoria — un secreto incorrecto o ausente se rechaza con 401:

curl -i -X POST http://127.0.0.1:8788/hook/test \
  -H 'X-Webhook-Secret: wrong' -d '{}'
# HTTP/1.1 401 Unauthorized

También hay un endpoint de disponibilidad:

curl http://127.0.0.1:8788/health
# {"ok":true,"hooks":["test"]}

• Se vincula a 127.0.0.1 por defecto — no es alcanzable desde la red.
• Cada hook requiere una credencial. Un hook sin secreto nunca se autentica.
• Secreto compartido — envíalo en el encabezado X-Webhook-Secret (se compara en tiempo constante).
• HMAC — configura un hmacSecret y firma el cuerpo crudo: X-Signature: sha256=<hex>.
• El tamaño del cuerpo tiene un límite (1 MB por defecto) para rechazar payloads demasiado grandes.

Cada sesión se vincula al primer puerto libre a partir de 8787 (8787, 8788, 8789, …), de modo que varias ventanas de free-code coexisten sin chocar entre sí. La URL de callback siempre refleja el puerto que una sesión efectivamente vinculó — compruébalo con /webhook url <name>.

Para fijar un puerto conocido:

# Por sesión, en vivo:
/webhook port 8790

# O configúralo antes de iniciar:
FREECODE_WEBHOOK_PORT=8790 free-code

Herramientas

Archivo de configuración — ~/.free-code/agent/webhook-receiver.json

{
  "enabled": true,
  "host": "127.0.0.1",
  "port": 8787,
  "portRange": 20,
  "publicBaseUrl": null,
  "defaultMode": "queue",
  "maxBodyBytes": 1048576,
  "hooks": {
    "flowise": { "mode": "trigger", "secret": "…" }
  }
}

Variables de entorno