EN Python Hooks and Custom Endpoints

Python hooks, dependencies and custom endpoints

English · Türkçe · Languages / Diller

Scope: JSON API Forge 0.5.1 · Source review: 17 September 2026 · Language: English

Hooks keep domain logic in ordinary Python functions, including third-party SDK calls, complex conditions and algorithms. They execute with the Forge process account's privileges. Treat permission to write hooks separately from permission to edit ordinary configuration.

A simple endpoint

app/WikiDemo/hooks/hello.py:

async def hello(*, request, payload, principal, app, project):
    return {"message": "Hello", "project": project.slug}

app/WikiDemo/config/60-custom.json:

{
  "custom_endpoints": [
    {
      "path": "hello",
      "method": "GET",
      "public": true,
      "handler": "app.WikiDemo.hooks.hello:hello",
      "input_mode": "none",
      "summary": "Simple public greeting",
      "response": {"kind": "json"}
    }
  ]
}

This public example returns no sensitive data. For a private endpoint, set an appropriate permission instead of public. The import form is module:function. Editing a Python hook does not mean JSON hot reload reimports it; restart/reload the Python worker.

Input and response types

Setting	Choices
input_mode	json, form, text, bytes, none
parameters[].location	query, header, cookie, path
Parameter types	string, integer, number, boolean
response.kind	json, text, html, redirect, stream, file, empty

Constrain JSON/form payloads with input_schema. Parameters support enums, numeric bounds, length and patterns. Handlers receive request/payload/principal/app/project keyword arguments. Accept the expected arguments or an appropriate **kwargs signature.

summary, description, tags, deprecated, include_in_schema and openapi_extra shape documentation, not access policy. Public endpoints receive an empty OpenAPI security array.

Dependencies

Entries in dependencies provide a name, callable: "module:function" and use_cache. Resources, operations and custom endpoints reference those names. Test the dependency's data connections and authorization assumptions. FastAPI dependency caching is distinct from HTTP response caching.

Background hooks

background_hooks schedules work after the response and adds result to the context. This is not a durable job queue. Worker termination can prevent completion, and redelivery is not guaranteed. Use a separate queue/outbox for critical email or business events. RPC idempotency replays do not schedule the hooks again.

Async behavior

Do not block async handlers with long synchronous network/disk SDK calls or CPU-heavy work. Bound external calls with timeouts, response limits, authorization and egress policy. Forge's built-in SSRF controls are not automatically applied to arbitrary Python HTTP code you write.

See the endpoint and operation models.

Sources and verification

This page describes the behavior at the pinned commits below. Recheck these contracts when upgrading.

• main/framework/hooks.py
• main/framework/factory.py
• main/framework/routers/project.py
• main/framework/responses.py

---

English home · All English pages · Version maintenance