Endpoint Management

An endpoint is an inbound relay URL. It examines the requests and sends the accepted traffic to the configured destinations.

Purpose#

Use this guide to:

• Create and edit endpoints.
• Set the method, the payload format, the retries, and the security.
• Set the field validation.
• Attach relay targets as destinations.
• Change the endpoint URL and the lifecycle state.

Before you start#

• A signed-in account.
• Relay targets that exist already.
• A relay target must be Available before you can select it as a destination. A platform email target needs the confirmation. A custom SMTP email target needs a successful connection test.

Procedure#

1. Create endpoint#

1. Open Endpoints and select Create endpoint.
2. In Details, enter these values:

• The name. This value is necessary, with a maximum of 100 characters.
• The description. This value is optional, with a maximum of 500 characters.
• The accepted HTTP method.
• The expected payload format. For GET and HEAD, only None and the query parameter formats are available.

3. Save the endpoint.

2. Configure details behavior#

• Any accepts every method. GET and HEAD still have no body.
• For a body-capable method (JSON, XML, Form, text/plain), the payload format must match the incoming Content-Type.
• The None format and the query parameter formats accept every Content-Type value.
• Ignore incoming Content-Type: if this control is enabled, PayloadRelay does not examine the Content-Type. All the other endpoint tests still apply. Use this control if a caller sends a wrong header or no header, but gives a payload in the configured format.

3. Configure delivery retries#

Set the delivery retries for each webhook destination in the Outputs tab:

• The default is 0. There are no retries.
• You can set a value to the maximum of your plan for each webhook.
• The plan limits are Sandbox 1, Solo 3, and Team trial, Team, and Scale 5. For a custom plan, the agreement of the organization sets the limit.
• Sandbox and Solo use the standard schedule. On the Team trial, Team, Scale, and an eligible custom plan, you can select an advanced schedule and custom retry status codes.
• A target with no retry configuration for the user uses an automatic retry schedule when PayloadRelay supports it. The same plan limit applies.

4. Configure security#

The Security tab supports these controls:

• Inbound authentication: None, Basic, Bearer token, API key header, or HMAC. For the provider presets, see HMAC Inbound Verification.
• Human verification: None, Cloudflare Turnstile, Google reCAPTCHA.
• Required request headers, with a maximum of 20 exact-value matches. A header name uses the normal HTTP token syntax, and the match ignores the case. A header name cannot be Authorization, Host, Content-Length, or a hop-by-hop or proxy header. PayloadRelay removes the spaces from a value when it saves the value, and the value cannot be empty. An incoming value must match exactly, with the same case and with no space removal. The required headers do not block a browser CORS preflight test.
• CORS origins. Enter one exact scheme://host[:port] value in each line. A blank value permits every browser origin.
• IP allowlist and IP version filter. These controls limit the traffic to IP addresses or CIDR blocks, and they can limit the traffic to IPv4 or IPv6. They apply to a webhook endpoint only. See IP Allowlists.

Rules:

• A captcha needs a body-capable method and a JSON, FORM, or XML payload format. It is not available for None, text/plain, or a query parameter format.
• The captcha supports Cloudflare Turnstile and Google reCAPTCHA. PayloadRelay stores the configured secret encrypted, and the API never returns it.
• The captcha field name is a JSON or form field key, a dot path such as captcha.token, or an XPath expression for XML. A missing token or an invalid token returns a 4xx status and records CAPTCHA_FAILED.
• To keep the stored values during an edit, leave the secret fields blank.
• Include captcha field in payload sets if the captcha token goes to the destinations, with Google Sheets. For a JSON payload and a form payload, PayloadRelay removes the token before the transforms and the delivery when this control is off. PayloadRelay sends the XML with no change.

5. Configure field validation#

Field validation is available in these conditions:

• The payload format is JSON, FORM, XML, Query Parameters, or Query Parameters (Base64 JSON).
• GET and HEAD support the field validation only with a query parameter format.

Supported validation types:

• ANY, STRING, INTEGER, FLOAT, BOOLEAN, EMAIL, REGEX

ANY does no type test. Use it with Required if the field must only exist.

Notes:

• Each endpoint can have a maximum of 20 rules. A field name and a selector can have a maximum of 200 characters. You cannot use the same value two times.
• A JSON, form, and query payload supports a dot-path field such as user.email or items.0.id. A numeric path segment gives the index in an array. PayloadRelay does not support the bracket notation such as items[0].id.
• XML supports XPath expressions.
• A type test uses the native JSON types when they are available. INTEGER, FLOAT, and BOOLEAN also accept the text equivalents from a form, query, and XML payload, such as "1", "1.5", or "true". REGEX and EMAIL apply to text values.
• A regex entry needs a valid Java-compatible regular expression of 500 characters or fewer. The matching has a time limit at relay time.
• The text/plain format and the None format do not apply the field validation.
• Query Parameters always makes a JSON object, and it supports the standard field validation rules. A necessary query parameter field must be in the URL. An explicit empty value (?key=) is present but blank.
• Query Parameters (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.

6. Configure request body filters#

A request body filter is an accept rule or a reject rule on the endpoint. The filters apply before the captcha, the field validation, the transforms, the quota consumption, and the delivery. All the configured filters must pass.

Supported filter types:

• CONTAINS: the raw body or the query string contains the configured value. The comparison is case-sensitive.
• MATCHES: the raw body or the query string is the same as the configured value.
• DOES_NOT_CONTAIN: the raw body or the query string does not contain the configured value.
• REGEX: a Java-compatible regular expression with a time limit on the partial matching.

Limits and behavior:

• Each endpoint can have a maximum of 10 unique body filter rules.
• A filter value is necessary and has a maximum of 4,096 characters. A regex pattern must also agree with the safe-regex limit.
• A JSON, XML, and text payload uses the raw UTF-8 request body. A form endpoint uses the raw form body. A query-parameter format uses the raw URL query string.
• A None payload clears the body filters, and PayloadRelay does not apply them.
• An HTTP request body filter that fails returns HTTP 400 and records REQUEST_BODY_FILTER_FAILED. An email body-as-payload filter records the same outcome and returns SMTP 550 to the sender.

7. Configure outputs#

1. In Outputs, attach one relay target or more. Each destination attaches an existing relay target in your account or organization to this endpoint. Its type is the target type (EMAIL, WEBHOOK, SLACK, DISCORD, GOOGLE_SHEETS, MICROSOFT_TEAMS, PAGERDUTY, or TELEGRAM). The API rejects a target with a different type and a target from a different organization.
2. Use Delivery enabled to keep a destination configured and stop the delivery to that target. A disabled endpoint stops every destination. A disabled destination stops that target only. The other enabled destinations still receive the deliveries.
3. Configure the values for each destination:

• Email: the subject, the Reply-To behavior, and the body format. A subject template removes CR, LF, and NUL after the formatting, to prevent a header injection. A blank formatted subject uses No subject. A Reply-To value must be an email address. A manual value and a fallback value cannot contain CR or LF.
• Available email body formats:
• RAW_PAYLOAD: the raw payload with formatting
• RAW_PAYLOAD_ROWS: the raw payload with one field in each row, and tab indentation for the nested fields
• TEXT: plain text, with an optional custom body template
• HTML: HTML, with an optional custom body template
• Slack: the Markdown control, on or off
• Discord: the TTS control, on or off, and an optional cut of a long message. The cut is off by default. If the cut is off, Activity records Discord content that is too large as a failed delivery.
• Microsoft Teams: optional message templates. PayloadRelay stores the destination credentials on the relay target.
• PagerDuty: PayloadRelay stores the integration key and the severity on the relay target. Create one PagerDuty target for each service or integration key.
• Telegram: optional message templates. PayloadRelay stores the bot token and the chat ID on the relay target.
• Google Sheets:
  • Save all fields to Sheet (on by default)
  • If Save all fields to Sheet is off, configure the exact fields to keep
• Webhook URL:
• Enforce HTTPS: PayloadRelay rejects the delivery if the target URL is not HTTPS. This control is enabled by default. An HTTPS connection always uses the normal TLS certificate validation. If you disable this control, PayloadRelay still rejects an invalid certificate.
• Outbound HTTP method: the outbound method, POST, PUT, or PATCH. The default is POST.
• Authentication: None, Basic, Bearer, or API Key. A Basic username cannot contain : or control characters.
• Custom headers: a maximum of 25 key-value pairs. A name has a maximum of 128 characters. A saved value has a maximum of 4,096 characters, and it can use a template variable such as {{fieldname}}, {{originating_ip}}, {{uuid}}, and {{email.subject}}. Mark a header that holds a credential as sensitive. PayloadRelay encrypts these values, and it does not show them after you save. Each header name must be unique. A header name cannot be a restricted HTTP header, it cannot conflict with the webhook authentication, and it cannot be the same as an outbound HMAC signature header, timestamp header, or previous-signature header.

  After the template variable resolution, PayloadRelay removes CR and LF from the outbound header values, and it limits a value to 8,192 characters. If PayloadRelay makes a value shorter, the delivery log records a warning for the target.

• Custom body: an optional body template with template variables. The saved template has a maximum of 65,536 characters. The formatted body has a maximum of 1 MiB. A custom body can use the inbound {{headers.Name}} and {{query.name}} values. For a channel-specific template, use Message Templates on a Slack, Discord, Microsoft Teams, or Telegram destination.
• Content-Type: an outbound content type that replaces the default. It must be a valid MIME type with a maximum of 100 characters.
• Forward incoming headers: PayloadRelay forwards all the headers or the selected headers from the incoming request.
• Forward response body: after a successful webhook delivery, PayloadRelay sends its response body to a different supported target. PayloadRelay does not send partial response data when the response is too large. Activity shows the response-forward attempt as failed. A PayloadRelay-to-PayloadRelay chain stops after three hops. Slack and Discord can shorten the content to their platform limits.
• Enable failover delivery: for a webhook destination, PayloadRelay sends the payload to a fallback destination after the primary webhook uses all the configured retries. The supported failover destinations are email, webhook, Slack, Discord, and Microsoft Teams. PayloadRelay does not support a Google Sheets, PagerDuty, or Telegram target for a failover.

4. Save the changes.

Notes:

• The enabled primary destinations have a limit for each endpoint: Sandbox 2, Solo 3, the Team trial and Team 5, and Scale 10. For a custom plan, the agreement of the organization sets the limit. A disabled destination configuration and a failover row do not count.
• If a downgrade makes the limit lower, the oldest permitted destinations stay enabled. PayloadRelay disables the extra destinations, and it keeps their configuration.
• If you remove a destination, the other destinations on the endpoint stay.
• An endpoint can have no destination. PayloadRelay accepts and records the relay requests, and it sends no delivery.
• If you delete an endpoint, PayloadRelay deletes its destinations. You cannot delete a relay target while a destination uses it.
• Configure the failover on the primary webhook destination, and not on the endpoint. A webhook failover destination has its own retry value. A different supported failover target uses its automatic retry behavior in the plan limit. Activity records a failover attempt as FAILOVER_TRIGGERED.

Restricted headers

When PayloadRelay forwards the incoming headers to a webhook target, with Forward all or with specific header names, PayloadRelay always removes these restricted headers:

Header	Reason
Host	PayloadRelay sets it for the destination
Connection	Hop-by-hop
Content-Length	PayloadRelay sets it from the outgoing body
Transfer-Encoding	Hop-by-hop
Upgrade	Hop-by-hop
Proxy-Authorization	Security-sensitive
Proxy-Connection	Hop-by-hop
TE	Hop-by-hop
Trailer	Hop-by-hop
Expect	Hop-by-hop
Keep-Alive	Hop-by-hop
HTTP2-Settings	Connection-specific
Authorization	Security-sensitive. Use the webhook authentication of the destination.
Cookie	Security-sensitive. A session token must not go to a target.
Set-Cookie	Security-sensitive. PayloadRelay must not forward this response header.
Content-Type	PayloadRelay sets it from the payload format and the content-type replacement
X-PayloadRelay-Forward-Chain	Signed loop-protection metadata that PayloadRelay manages
X-PayloadRelay-Delivery-Id	Delivery identity metadata that PayloadRelay manages
X-PayloadRelay-Event-Id	Event identity metadata that PayloadRelay manages
X-PayloadRelay-Attempt	Delivery-attempt metadata that PayloadRelay manages

PayloadRelay also removes the endpoint-specific credential headers and validation headers: each configured required request header, the configured inbound API-key header, the inbound HMAC signature header, and the Slack timestamp header when the Slack HMAC preset is active. PayloadRelay never gives these dynamic names to a body template, and it never forwards them automatically. If you select one of them, the protection stays. If the destination needs its own credential, add the value separately as outbound authentication or as a sensitive custom header on the destination.

If Forward all incoming headers is enabled, PayloadRelay removes the static headers and the endpoint-specific headers in the list above. If you add a static restricted name to the list of specific forwarded headers, the API rejects the configuration and does not save a value that it ignores. PayloadRelay can forward all the other incoming headers.

Google Sheets delivery behavior

• PayloadRelay adds each accepted payload as a new row.
• PayloadRelay matches the columns to the field names, and it ignores the case.
• PayloadRelay creates a missing column automatically, and it uses the field name as the header.
• For an XML, text/plain, and None flow, payload is the only supported configured field.
• For a query parameter format, also on GET and HEAD, you can select the individual parsed fields.

8. Configure email ingestion#

Email ingestion permits an endpoint to receive an email as a relay payload. It needs no HTTP request.

1. In the header of the endpoint editor, select Email ingestion endpoint in the Endpoint type list.
2. Save the endpoint.
3. Open the saved endpoint and copy the emailIngestionAddress that the API gives.
4. Use that address as a recipient in the system that sends the email.
5. PayloadRelay converts the incoming email into a JSON payload with the sender, the recipients, the subject, the text body and the HTML body, the headers, and the metadata.
6. PayloadRelay removes the attachments. It relays the text content only.
7. Each new accepted inbound email consumes one accepted event from the monthly quota. A completed second delivery that PayloadRelay identifies consumes no quota.

Notes:

• An endpoint is a Webhook endpoint or an Email ingestion endpoint. It cannot be both.
• A change of the endpoint type clears the values for that type. For example, a change to email clears the inbound authentication, the captcha, the IP limits, the CORS, and the required headers.
• The endpoint must be enabled to accept an inbound email.
• Activity shows Email Accepted (EMAIL_INGESTION_ACCEPTED) for an accepted email relay. A rejection uses the most specific outcome that is available, such as Auth Failed (AUTH_FAILED), Body Filter Failed (REQUEST_BODY_FILTER_FAILED), Validation Failed (FIELD_VALIDATION_FAILED), Malformed JSON Payload (MALFORMED_JSON_PAYLOAD), or Email Rejected (EMAIL_INGESTION_REJECTED).

9. Pause and auto-resume#

Pause an endpoint for a period, and do not disable it. During the pause, a webhook request receives 503 Service Unavailable. An inbound email receives a temporary SMTP 451. The two responses create no Request activity row.

To pause an endpoint:

1. Open the endpoint in the editor.
2. Select the Pause button beside the enable control.
3. Select 1 hour, 6 hours, 24 hours, or Custom… for 1 to 43,200 minutes.
4. Read the badge, such as Paused. The endpoint resumes in 3h 20m.

To resume early:

• To clear the pause immediately, select Resume now in the pause badge.
• The endpoint accepts traffic again immediately.

Behavior notes:

• A webhook request during a pause receives HTTP 503. An email sender receives SMTP 451. The mail server of the sender controls the retry period, and it can stop before a long pause ends.
• The endpoint resumes after the selected period. You do not have to do anything.
• A pause is different from a disable. An endpoint with enabled=false returns 404. A paused endpoint returns 503.
• PayloadRelay keeps the selected resume time until the endpoint resumes automatically, or until you resume it manually.

10. URL rotation and lifecycle actions#

• Regenerate URL creates a new endpoint URL immediately.
• The old URL stops to accept requests immediately.
• You can enable or disable the endpoint.
• Delete removes the endpoint and its related Activity history permanently.

11. Failure-rate alerts#

Configure an alert for each endpoint. The alert fires when the failure rate in a rolling window is equal to a threshold or higher. You can also pause the endpoint automatically when an alert fires. For the details, see the Failure-Rate Alerts guide.

Expected result#

• The endpoint appears with the expected method, format, and security configuration.
• The accepted traffic appears as Pending while the deliveries are in progress, then it moves to a final outcome. The dashboard shows the label Completed for final ACCEPTED traffic.
• The selected destinations receive the deliveries.
• A Google Sheets destination adds rows to the selected spreadsheet and sheet.

Common issues and fixes#

• "No relay targets": create the targets first.
• The email destination is not available: make sure that the email target is available.
• PayloadRelay rejects the Google Sheets field selection: if Save all fields to Sheet is off, add a field. Use payload only for an XML, text/plain, or None endpoint.
• Validation errors: examine the field names, the types, and the patterns.
• Captcha errors: make sure that the token field name and the provider secret are correct.
• Delivery errors: examine the target URL, the authentication, the headers, and the TLS configuration.
• Unexpected 3xx failures: PayloadRelay does not obey an HTTP redirect. A webhook target must answer directly with a 2xx status code.

Throughput controls#

For each endpoint, you can set Max requests per minute in the Details tab. To use the default of your subscription tier, leave it blank. You can also enter a positive integer to the limit of your tier. A request above the effective limit returns 429 Too Many Requests with a Retry-After header, and Activity records RATE_LIMITED_ENDPOINT.

Related guides#

• Relay Targets
• Email Ingestion
• HTTP Methods and Payload Formats
• Authentication and Secrets
• Routing Filters
• Sending Data to an Endpoint
• Troubleshooting Ingest
• Observability
• Audit Log: track the endpoint lifecycle events.