Choosing Proxy vs Service Execution
Use this page when you are deciding whether a route should proxy upstream HTTP or execute worker code directly. Proxy routes (`http_proxy`) forward requests to
Last updated
Use this page when you are deciding whether a route should proxy upstream HTTP or execute worker code directly. Proxy routes (`http_proxy`) forward requests to
Use this page when you are deciding whether a route should proxy upstream HTTP or execute worker code directly. Proxy routes (http_proxy) forward requests to external HTTP endpoints, while service routes call local or bound Worker code. This page compares latency, coupling, and deployment tradeoffs to help you choose.
Last reviewed: 2026-03-06
Use the service execution recipes when your routes need to call Worker code directly instead of proxying to an external HTTP endpoint. The gateway supports two patterns: local service modules bundled with the worker, and service bindings that call separately deployed Workers via Cloudflare bindings.
The service integration type imports a local JavaScript module from the worker project and calls its default export. The module ships in the same worker bundle.
The service_binding integration type calls a separately deployed Worker through a Cloudflare service binding. The target Worker must be deployed independently and bound in wrangler.toml.
Pre-process hooks run before the main integration and can short-circuit the request by returning a response. Use them for custom authorization, input validation, or request enrichment.
Post-process hooks run after the main integration returns and can modify the response. The Auth0 callback post-process hook is the most common use case.
When choosing between proxy and service execution, consider latency (service bindings avoid an external HTTP round-trip) and coupling (proxy keeps the backend independently deployable).
{
"servers": [
{ "alias": "upstream", "url": "https://api.example.com/base" }
],
"paths": [
{
"method": "GET",
"path": "/proxy/{.+}",
"integration": {
"type": "http_proxy",
"server": "upstream"
}
}
]
}This snippet uses an http_proxy integration that forwards requests to an external upstream. Compare this with the service or service_binding integration types, which execute Worker code directly without an external HTTP round-trip.
If a service integration returns 500, confirm that the entrypoint path in the services array matches the actual file location relative to the worker root and that the module exports a default function.
If a service_binding integration returns a binding error, verify that the binding name in config matches the binding declared in wrangler.toml and that the target Worker is deployed.
If a pre-process hook does not short-circuit as expected, check that the hook function returns a Response object -- returning undefined or null lets the request continue to the main integration.
If post-process hooks are not running, confirm the hook config uses the correct binding and function field names and that the hook Worker is deployed and bound.
Last updated