Skip to main content

HTTP Request

Overview​

The HTTP Request Traffic Policy action performs an outbound HTTP request to a target URL. You can use it to integrate with external services through internal endpoints or—if enabled—with external APIs.

Note: External requests are supported but disabled by default. Contact ngrok support to enable external access.

Configuration Reference​

The Traffic Policy configuration reference for this action.

Supported Phases​

on_http_request, on_http_response

Type​

http-request

Configuration Fields​

  • urlstringRequiredCEL

    The destination URL for the HTTP request.

  • methodenum

    The HTTP method to use for the request.

    • Possible enum values
    • GET (default)
    • PUT
    • POST
    • PATCH
    • DELETE
    • OPTIONS

  • query_paramslist of objectsCEL

    A list of query parameters to append to the URL. Each item is an object with the following structure:

    Loading…

    This format supports CEL interpolation in both keys and values.

    Maximum: 32 entries. Key max length: 128 chars. Value max length: 8192 chars.

  • headersobjectCEL

    A map of HTTP headers to include in the request. Keys are header names and values are header values.

    Maximum: 10 entries.

  • bodystringCEL

    The body of the HTTP request. Supported on methods like POST, PUT, or PATCH.

  • max_redirectsint

    The maximum number of HTTP redirects to follow.

    Default is 10. The minimum allowed is 0. The maximum allowed is 100.

  • timeoutduration

    The maximum duration as a duration string to wait for the entire request (including retries and redirects).

    Default is 3s. The minimum allowed is 1s. The maximum allowed is 30s.

  • retry_conditionstringCEL

    A CEL expression evaluated after each failed attempt. If true, the request is retried (up to 3 times).

    • Supported retry variables
    • attempts (int): Total number of attempts so far
    • last_attempt.req: The last request object
    • last_attempt.res: The last response object (if any)
    • last_attempt.error: The error string (if any)

    Default: false

  • on_errorenum

    Determines how to proceed if the HTTP request fails.

    • Possible enum values
    • continue (default) – Proceed with remaining actions
    • halt – Stop processing the policy

Behavior​

The http-request action issues an outbound HTTP request during either the on_http_request or on_http_response phase of policy execution. It can include dynamic headers, query parameters, and a request body.

Only specific HTTP methods are supported: GET, POST, PUT, PATCH, DELETE, and OPTIONS. If no method is specified, GET is used by default.

Internal Endpoint Behavior​

By default, the http-request action only supports requests to internal ngrok endpoints. Requests to internal endpoints (those with .internal domains) are treated differently from public (or external) requests, these requests must resolve to an internal ngrok endpoint running on your account.

These requests also use a direct connection over ngrok's control plane and do not rely on the public internet. If the request targets an internal agent endpoint (e.g., your self-hosted ngrok agent), it will exit the control plane and traverse the public internet to reach your agent running locally.

Retry Logic​

You can use a condition to automatically retry failed requests. This is useful for handling transient errors, like a 500 response. The condition is written using an expression language and has access to:

  • attempts: number of attempts so far
  • last_attempt.req: the most recent request
  • last_attempt.res: the most recent response
  • last_attempt.error: any error that occurred
Loading…

The request will retry up to 3 times.

Timeout Behavior​

The timeout setting defines the maximum total time allowed for the entire http-request action, including all retry attempts. This prevents long-running or stalled requests from delaying policy evaluation.

The default timeout is 3s. You can configure any duration between 1 second and 30 seconds using standard duration formats like 5s or 10s.

Timeout Error Handling​

Whether a timeout causes the policy to fail or continue depends on the on_error setting:

  • halt will treat the timeout as a hard failure.
  • continue will move forward even if the request timed out.

Loop Protection​

To prevent endless loops between services, ngrok tracks internal hops. If the same request loops more than 3 times internally, it will be stopped automatically.

Redirect Behavior​

By default, the http-request action does not follow HTTP redirects. You can enable redirect handling by setting the max_redirects field. The allowed range is 0 to 5. By default it is set to 0.

If the number of redirects exceeds max_redirects, the action fails. Redirect handling only applies to 3xx responses from the target server.

Response Body Size Limits​

The response body returned by the http-request action is limited to 256 KB. If the body size exceeds this limit, the action fails and returns a response size exceeded error.

This limit applies to the decoded body after any decompression and before retries are evaluated.

Each retry is also subject to the 256 KB response size limit. If the response body exceeds this limit, the attempt fails and the error is included in the retry_condition evaluation.

Error Handling​

Set on_error to control what happens if the request fails:

  • continue: Policy continues even if the request fails.
  • halt: Policy stops immediately on failure.

This gives you control over how critical the request is to your policy logic.

Automatically Injected Headers​

ngrok automatically injects some headers into your request to help with debugging, tracing and abuse:

HeaderPurpose
Ngrok-Report-AbuseStatic URL for reporting abuse
Ngrok-Req-TypeAlways set to http-request
Ngrok-Req-IdUnique request identifier
X-Forwarded-ForOriginal client IP address
User-AgentIdentifies the request as from ngrok/cloud

CEL Interpolation​

Certain fields in the http-request action support CEL (Common Expression Language) interpolation, allowing dynamic values based on the request context.

The following fields support CEL expressions:

  • url
  • headers (values only)
  • query_params (values only)
  • body

Expressions must be wrapped in ${...} and are evaluated at runtime using the current request data.

Examples​

Make a GET request​

Performs a simple GET request to an internal endpoint.

Loading…

Make a POST request​

This example sends a POST request to an internal endpoint with a custom JSON body and headers.

To simulate this behavior, we'll use httpbin.org/post behind an internal .internal endpoint.

Start an Internal Agent Endpoint​

Loading…

Example​

Loading…

Send query parameters​

This example sends a GET request with custom query parameters to an internal endpoint.

To simulate this behavior, we'll use httpbin.org/get, which echoes query parameters in the response.

Start an Internal Agent Endpoint​

Loading…

Example​

Loading…

Follow redirects​

This example demonstrates how to follow up to 2 redirects using the http-request action.

To simulate this behavior, we'll use httpbin.org/redirect behind an internal .internal endpoint.

Start an Internal Agent Endpoint​

Run the following command to expose https://httpbin.internal as a simulated internal service:

Loading…

Example​

Loading…

Action Result Variables​

The following variables are made available for use in subsequent expressions and CEL interpolations after the action has run. Variable values will only apply to the last action execution, results are not concatenated.

  • actions.ngrok.http_request.error.codestring

  • actions.ngrok.http_request.error.messagestring

    Message for an error that occurred during the invocation of an action.

  • actions.ngrok.http_request.attemptsarray of objects

    A list of HTTP responses for each request attempt.

  • actions.ngrok.http_request.reqobject

    The HTTP request.

  • actions.ngrok.http_request.resobject

    The last attempted HTTP response. Unlike actions.ngrok.attempts[i] this variable also contains the response body.