HTTP Macros

ngrok provides additional CEL macros that you can use specifically in the on_http_request and on_http_response phases.

Name	Return Type	Description
hasReqHeader(string)	bool	Returns true or false if the provided header key is present on the request.
getReqHeader(string)	list	Returns a list of header values for the provided key on the request.
hasQueryParam(string)	bool	Returns true or false if the specified query parameter key is part of the request URL.
getQueryParam(string)	list	Returns a list of the query parameter values from the request URL for the specified key.
hasReqCookie(string)	bool	Returns true or false if a cookie exists on the request with the specified name.
getReqCookie(string)	cookie	Returns the cookie struct for the specified cookie name, if it exists on the request. If there are multiple cookies of the same name, the first from the ordering specified in the Cookie header will be returned.
hasResHeader(string)	bool	Returns true or false if the provided header key is present on the response.
getResHeader(string)	list	Returns a list of header values for the provided key on the response.
hasResCookie(string)	bool	Returns true or false if a cookie exists on the response with the specified name.
getResCookie(string)	cookie	Returns the cookie struct for the specified cookie name, if it exists on the response. If there are multiple cookies of the same name, the cookie with the longest path will be returned.

on_http_*

The following macros can be used in both the on_http_request and on_http_response phases.

hasReqHeader(string) -> bool

Returns true or false if the provided header key is present on the request. Header keys must be written in canonical format.

Example

hasReqHeader('Authorization')

Example (Expression)

YAML

# snippet
---
expressions:
  - hasReqHeader('X-Version-Id')

JSON

// snippet
{
  "expressions": [
    "hasReqHeader('X-Version-Id')"
  ]
}

getReqHeader(string) -> list

Returns a list of header values for the provided key on the request. Header keys must be written in canonical format.

Example

getReqHeader('User-Agent')

Example (Expression)

YAML

# snippet
---
expressions:
  - getReqHeader('User-Agent').exists(v, v.matches('(?i)google-images'))

JSON

// snippet
{
  "expressions": [
    "getReqHeader('User-Agent').exists(v, v.matches('(?i)google-images'))"
  ]
}

hasQueryParam(string) -> bool

Returns true or false if the specified query parameter key is part of the request URL.

Example

hasQueryParam('query')

Example (Expression)

YAML

# snippet
---
expressions:
  - hasQueryParam('q')

JSON

// snippet
{
  "expressions": [
    "hasQueryParam('q')"
  ]
}

getQueryParam(string) -> list

Returns a list of the query parameter values from the request URL for the specified key.

Example

getQueryParam('search')

Example (Expression)

YAML

# snippet
---
expressions:
  - size(getQueryParam('q')) == 0

JSON

// snippet
{
  "expressions": [
    "size(getQueryParam('q')) == 0"
  ]
}

hasReqCookie(string) -> bool

Returns true or false if a cookie exists on the request with the specified name.

Example

hasReqCookie('session')

Example (Expression)

YAML

# snippet
---
expressions:
  - hasReqCookie('session')

JSON

// snippet
{
  "expressions": [
    "hasReqCookie('session')"
  ]
}

getReqCookie(string) -> cookie

Returns the cookie struct for the specified cookie name, if it exists on the request. If there are multiple cookies of the same name, the first from the ordering specified in the Cookie header will be returned.

Example

getReqCookie('session')

Example (Expression)

YAML

# snippet
---
expressions:
  - getReqCookie('session').secure

JSON

// snippet
{
  "expressions": [
    "getReqCookie('session').secure"
  ]
}

on_http_response

The following macros can only be used in the on_http_response phase.

hasResHeader(string) -> bool

Returns true or false if the provided header key is present on the response. Header keys must be written in canonical format.

Example

hasResHeader('Content-Type')

Example (Expression)

YAML

# snippet
---
expressions:
  - hasResHeader('Content-Type')

JSON

// snippet
{
  "expressions": [
    "hasResHeader('Content-Type')"
  ]
}

getResHeader(string) -> list

Returns a list of header values for the provided key on the response. Header keys must be written in canonical format.

Example

getResHeader('Content-Type')

Example (Expression)

YAML

# snippet
---
expressions:
  - size(getResHeader('Content-Type').filter(v, v.matches('application/json')))
    > 0

JSON

// snippet
{
  "expressions": [
    "size(getResHeader('Content-Type').filter(v, v.matches('application/json'))) > 0"
  ]
}

hasResCookie(string) -> bool

Returns true or false if a cookie exists on the response with the specified name.

Example

hasResCookie('_device_id')

Example (Expression)

YAML

# snippet
---
expressions:
  - hasResCookie('_device_id')

JSON

// snippet
{
  "expressions": [
    "hasResCookie('_device_id')"
  ]
}

getResCookie(string) -> cookie

Returns the cookie struct for the specified cookie name, if it exists on the response. If there are multiple cookies of the same name, the cookie with the longest path will be returned.

Example

getResCookie('_device_id')

Example (Expression)

YAML

# snippet
---
expressions:
  - getResCookie('_device_id').value == 'mobile-phone-14'

JSON

// snippet
{
  "expressions": [
    "getResCookie('_device_id').value == 'mobile-phone-14'"
  ]
}