Query Parameters

Parse URL query parameters as key-value pairs or Base64-encoded JSON.

5 min read

If a sender puts data in the URL instead of the request body, use a query parameter format.

Purpose#

This guide covers:

The query parameter formats and their uses.
The supported values and the parsing rules.
The Base64 JSON configuration.
The effect on the field validation, the captcha, and the relay targets.

Before you start#

Create access or edit access for an endpoint.
Knowledge of the request format of the sender.

Available query parameter formats#

None (ignore body)#

If the endpoint must accept a request with no payload, select None (ignore body). PayloadRelay ignores the request body, with any content type. Use this format for a health check, a simple trigger, or a fire-and-forget notification.

Query Parameters#

PayloadRelay parses all the query parameters from the URL into a flat JSON object. Each parameter becomes a key-value pair.

Supported value formats:

URL value	Parsed as	Example
Plain string	String	`?name=John` becomes `{"name": "John"}`
Number	String	`?count=42` becomes `{"count": "42"}`
Boolean	String	`?active=true` becomes `{"active": "true"}`
Multi-value	Array of strings	`?tag=a&tag=b` becomes `{"tag": ["a", "b"]}`
Empty / no value	Empty string	`?flag=` or `?flag` becomes `{"flag": ""}`
URL-encoded	Decoded string	`?msg=hello%20world` becomes `{"msg": "hello world"}`

Example request:

GET https://api.payloadrelay.com/relay/abc123?name=John&age=30&active=true

Parsed payload sent to relay targets:

{
  "name": "John",
  "age": "30",
  "active": "true"
}

PayloadRelay parses a single query parameter value as a string. A repeated parameter becomes an array of strings.

Query Parameters (Base64 JSON)#

One query parameter contains the complete payload as a Base64-encoded JSON string. This format supports nested objects, arrays, and typed values in a URL.

Use this format as follows:

The sender encodes a JSON payload in Base64.
The sender sends the encoded string as one query parameter.
PayloadRelay decodes the Base64 string and parses the JSON.
PayloadRelay sends the parsed JSON to all the relay targets.

Encoding support: PayloadRelay accepts the standard Base64 and the URL-safe Base64. The URL-safe Base64 uses - and _ in place of + and /. Percent-encode + and / in a URL. PayloadRelay also accepts an unescaped + in this encoded value.

Configuration:

When you select this format, two more values appear:

The query parameter name. This value is necessary and has a maximum of 255 characters. It is the URL parameter that contains the encoded payload. PayloadRelay rejects a space, a control character, #, and ?. You can use a URL-special character such as + or & when the sender percent-encodes the parameter name.
The required parameter control. It is enabled by default. When it is enabled, PayloadRelay rejects a request with no such parameter and returns a 400 error. When it is disabled, PayloadRelay uses a missing parameter as an empty payload.

Example:

Given query parameter name data:

Original JSON payload:

{"name": "John", "age": 30, "items": ["a", "b"]}

Base64-encoded: eyJuYW1lIjoiSm9obiIsImFnZSI6MzAsIml0ZW1zIjpbImEiLCJiIl19

Request URL:

GET https://api.payloadrelay.com/relay/abc123?data=eyJuYW1lIjoiSm9obiIsImFnZSI6MzAsIml0ZW1zIjpbImEiLCJiIl19

PayloadRelay sends the decoded JSON to the relay targets with no change.

Feature interactions#

Feature	None	Query Parameters	Base64 JSON
Field validation	Disabled	Enabled	Object payloads only
Captcha	Disabled	Disabled	Disabled
Google Sheets fields	`payload` only	All fields	All fields
Email formatting	Empty payload	JSON formatting	JSON formatting
Webhook forwarding	Empty body	JSON body	JSON body

Field validation#

The None format has no payload to examine. The field validation is disabled.
Query Parameters always makes a JSON object, and it supports the standard field validation rules (the type tests, the necessary fields, and the regex patterns).
Base64 JSON supports the field validation when the root of the decoded JSON is an object. PayloadRelay sends an array and a scalar JSON value to the relay targets, but the field validation rules cannot apply to them.

Captcha verification#

The captcha verification is not available with these formats. A captcha token is usually in a JSON, form, or XML request body.

Google Sheets#

The None format: PayloadRelay supports the synthetic payload field only.
Query Parameters and Base64 JSON: all the parsed JSON fields are available for the column mapping.

Body handling#

When you select None, Query Parameters, or Query Parameters (Base64 JSON), PayloadRelay ignores the request body, with any method and any content type. The endpoint accepts all the Content-Type headers.

Error handling#

Scenario	Outcome
A necessary Base64 parameter is missing	`MALFORMED_QUERY_PARAM` (400)
The Base64 encoding is invalid	`MALFORMED_QUERY_PARAM` (400)
The Base64 value decodes, but it is not valid JSON	`MALFORMED_QUERY_PARAM` (400)
The Base64 JSON is larger than the plan payload size limit	`PAYLOAD_TOO_LARGE` (413)
The query string is larger than the plan payload size limit	`PAYLOAD_TOO_LARGE` (413)
More than 64 query parameter pairs	`MALFORMED_QUERY_PARAM` (400)
No query parameter (Query Params mode)	PayloadRelay sends an empty JSON object `{}`
An optional Base64 parameter is missing	PayloadRelay sends an empty payload

HTTP method compatibility#

The GET and HEAD methods support None, Query Parameters, and Query Parameters (Base64 JSON) only.
All the other methods support all the formats, with the query parameter formats.

← Back to documentation