← Back to documentation

Endpoint Management

Full guide for creating and maintaining endpoints that reliably accept and forward traffic.

14 min read

Endpoints are inbound relay URLs. They validate requests, then forward accepted traffic to configured outputs.

Purpose

Use this guide to:

  • Create/edit endpoints.
  • Configure method, payload format, retries, and security.
  • Configure field validation.
  • Attach outputs (destinations).
  • Rotate URLs and manage endpoint lifecycle.

Prerequisites and permissions

  • Signed-in account.
  • Relay targets already created.
  • Email targets must be Confirmed before they can be selected as outputs.

Step-by-step workflow

1. Create endpoint

  1. Open Endpoints and select Create endpoint.
  2. In Details, set:
  • Name (required, max 100)
  • Optional description (max 500)
  • Accepted HTTP method
  • Expected payload format (for GET/HEAD, only None and query parameter formats are available)
  1. Save endpoint.

2. Configure details behavior

  • Any method accepts all methods, but GET/HEAD still have no body.
  • Payload format must match incoming Content-Type for body-capable methods (JSON, XML, Form, text/plain).
  • None and query parameter formats accept any Content-Type.
  • Ignore incoming Content-Type: when enabled, the endpoint accepts requests regardless of Content-Type header. Use this when callers send a mismatched or missing Content-Type but still deliver valid payloads.

3. Configure delivery retries

Delivery retries are configured per webhook output in the Target destination tab:

  • Default 0 (no retries)
  • Configurable up to your plan max per webhook
  • BASIC plan max is 0
  • Non-webhook targets (email, Slack, Discord, Google Sheets) automatically retry 5 times — no configuration needed

4. Configure security

Security tab supports:

  • Inbound auth: None, Basic, Bearer token, API key header, or HMAC (provider presets are covered in HMAC Inbound Verification)
  • Human verification: None, Cloudflare Turnstile, Google reCAPTCHA
  • Required request headers (up to 20 exact-value matches). Header names use normal HTTP token syntax, are matched case-insensitively, and cannot be Authorization, Host, Content-Length, or hop-by-hop/proxy headers. Values are trimmed when saved, must be non-empty, and incoming values must match exactly (case-sensitive, no trimming). Browser CORS preflight checks are not blocked by required headers.
  • CORS origins (one per line; exact scheme://host[:port] matches; blank means allow any browser origin)
  • IP allowlist and IP version filter — restrict traffic to specific IPs/CIDR blocks and optionally IPv4 or IPv6 only (webhook endpoints only). See IP Allowlists for details.

Rules:

  • Captcha requires a body-capable method and JSON, FORM, or XML payload format. Not available for None, text/plain, or query parameter formats.
  • Captcha supports Cloudflare Turnstile (https://challenges.cloudflare.com/turnstile/v0/siteverify) and Google reCAPTCHA (https://www.google.com/recaptcha/api/siteverify). The configured secret is stored encrypted and never returned by the API.
  • The captcha field name is a JSON/form field key or dot path (for example captcha.token) or an XPath expression for XML. Missing or invalid tokens return a 4xx and log CAPTCHA_FAILED.
  • Leave secret fields blank during edit to keep stored values.
  • Include captcha field in payload controls whether the verified captcha token is forwarded to outputs, including Google Sheets. For JSON/form payloads, unchecked strips the token before transforms and dispatch; XML is forwarded verbatim.

5. Configure field validation

Field validation is available when:

  • Payload format is one of JSON, FORM, XML, Query Parameters, or Query Parameters (Base64 JSON)
  • GET/HEAD only support field validation when using a query parameter format

Supported validation types:

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

ANY performs no type check; use it with Required when you only need to require that a field exists.

Notes:

  • Up to 20 rules are allowed per endpoint. Field names/selectors must be 200 characters or less and cannot be duplicated.
  • JSON/form/query payloads support dot-path fields (for example user.email or items.0.id). Numeric path segments index arrays; bracket notation such as items[0].id is not supported.
  • XML supports XPath expressions.
  • Type checks use native JSON types when available. INTEGER, FLOAT, and BOOLEAN also accept textual equivalents from form/query/XML payloads (for example "1", "1.5", or "true"); REGEX and EMAIL apply to text values.
  • Regex entries require a valid Java regex pattern of 500 characters or less. Regex matching is time-limited at relay time.
  • text/plain and None formats do not run field validation.
  • Query Parameters always produce a JSON object and support the standard field validation rules. A required query parameter field must be present in the URL; an explicit empty value (?key=) is present but blank.
  • Query Parameters (Base64 JSON) supports field validation when the decoded JSON root is an object. Arrays and scalar JSON values are forwarded to relay targets, but field validation rules cannot be applied to them.

6. Configure request body filters

Request body filters are endpoint-level accept/reject rules that run before captcha, field validation, transforms, quota consumption, and dispatch. All configured filters must pass.

Supported filter types:

  • CONTAINS — raw body/query string contains the configured value (case-sensitive)
  • MATCHES — raw body/query string exactly equals the configured value
  • DOES_NOT_CONTAIN — raw body/query string does not contain the configured value
  • REGEX — Java regular expression with time-limited find() semantics

Limits and behavior:

  • Up to 10 unique body filter rules per endpoint.
  • Filter values are required and capped at 4,096 characters; regex patterns must also satisfy the safe-regex limit.
  • JSON, XML, and text payloads filter the raw UTF-8 request body; form endpoints filter the raw form body; query-parameter formats filter the raw URL query string.
  • None payloads clear/skip body filters.
  • Failed HTTP webhook body filters return 400 and log REQUEST_BODY_FILTER_FAILED; email body-as-payload failures log EMAIL_INGESTION_REJECTED.

7. Configure target destinations (outputs)

  1. In Target destinations, select one or more relay targets. Each output points at an existing relay target in your account or organization; its output type is the target type (EMAIL, WEBHOOK, SLACK, DISCORD, GOOGLE_SHEETS, MICROSOFT_TEAMS, PAGERDUTY, or TELEGRAM), and mismatched or foreign targets are rejected by the API.
  2. Use Delivery enabled to keep an output configured but skip dispatching to that target. Disabled endpoints skip all outputs; disabled outputs skip only that target while other enabled outputs still receive deliveries.
  3. Configure output-specific settings:
  • Email: subject, reply-to behavior, and body format. Subject templates strip CR/LF/NUL after rendering to block header injection; blank rendered subjects fall back to No subject. Reply-To settings are validated as email addresses, and manual/fallback values cannot contain CR/LF.
  • Available email body formats:
  • RAW_PAYLOAD: pretty-printed raw payload
  • RAW_PAYLOAD_ROWS: raw payload rendered as one field per row with tab-indented nesting
  • TEXT: plain text with optional custom body template
  • HTML: HTML with optional custom body template
  • Slack: markdown on/off
  • Discord: TTS on/off
  • Google Sheets:
  • Save all fields to Sheet (default on)
  • When Save all fields to Sheet is off, configure the exact fields to persist
  • Webhook URL:
  • Require valid SSL certificate: enforces HTTPS with a valid certificate (default on)
  • Outbound HTTP method: HTTP method used for outbound delivery — POST, PUT, or PATCH (default POST)
  • Authentication: None, Basic, Bearer, API Key
  • Custom headers: up to 25 key-value pairs. Names are capped at 128 characters; saved values are capped at 4,096 characters and may use template variables ({{fieldname}}, {{originating_ip}}, {{uuid}}, {{email.subject}}, etc.). Header names must be unique and cannot use restricted HTTP headers, conflict with webhook auth, or collide with outbound HMAC signature/timestamp/previous-signature headers.

    Note: After template variable resolution, CR/LF is stripped from outbound header values and values are truncated to 8,192 characters. If truncation occurs, a warning is recorded in the delivery log for the affected target.

  • Custom body: optional body template with template variable support (saved template up to 65,536 characters; resolved body is capped at 1 MiB). Custom bodies can also reference inbound {{headers.Name}} and {{query.name}} values. For channel-native templating, use Message Templates on Slack, Discord, Microsoft Teams, or Telegram outputs.
  • Content-Type: override the outbound content type (valid MIME type, max 100 characters)
  • Forward incoming headers: forward all or specific headers from the incoming request
  • Enable failover delivery: for webhook outputs, dispatch the payload to a fallback target after the primary webhook exhausts its configured retries. Supported failover delivery targets are email, webhook, Slack, and Discord. Google Sheets targets are not supported for failover.
  1. Save changes.

Notes:

  • Removing an output does not remove other outputs on the endpoint.
  • Endpoints may have zero outputs; relay requests are accepted and logged, but no deliveries are sent.
  • Deleting an endpoint deletes its outputs. A relay target cannot be deleted while an endpoint output still references it.
  • Failover is configured on the primary webhook output, not at the endpoint level. If the failover target is another webhook, it has its own retry setting; supported non-webhook failover targets use their standard automatic retry behavior. Activity logs failover dispatches with FAILOVER_TRIGGERED.

Restricted headers

When forwarding incoming headers to a webhook target (either "Forward all" or specific header names), PayloadRelay always strips the following restricted headers:

HeaderReason
HostSet by the HTTP client for the target host
ConnectionHop-by-hop; managed by the HTTP client
Content-LengthRecalculated for the outbound body
Transfer-EncodingManaged by the HTTP client
UpgradeHop-by-hop
Proxy-AuthorizationSecurity-sensitive
Proxy-ConnectionHop-by-hop
TEHop-by-hop
TrailerHop-by-hop
ExpectHop-by-hop
Keep-AliveHop-by-hop
HTTP2-SettingsConnection-specific
AuthorizationSecurity-sensitive; use per-output webhook auth instead
CookieSecurity-sensitive; session tokens must not leak to targets
Set-CookieSecurity-sensitive; response header that must not be forwarded
Content-TypeSet by the webhook request builder based on payload format and content-type override

When Forward all incoming headers is enabled, these headers are silently dropped. If you add a restricted header name to the specific forwarded-headers list, the API rejects the configuration instead of saving an ignored value. This list is exhaustive for forwarded incoming headers — all other incoming headers are eligible for forwarding.

Google Sheets delivery behavior

  • Each accepted payload is appended as a new row.
  • Columns are matched to field names case-insensitively.
  • Missing columns are created automatically using the field name as the header.
  • For XML, text/plain, and None flows, the only supported configured field is payload.
  • Query parameter formats, including GET/HEAD, support selecting individual parsed fields.

8. Configure email ingestion

Email ingestion lets your endpoint receive email as relay payloads — no HTTP request required.

  1. In the endpoint editor header, select Email ingestion endpoint from the Endpoint type dropdown.
  2. The endpoint's email address is shown: {endpointId}@payloadrelay.com
  3. Copy the email address and use it as a recipient wherever email is sent.
  4. Incoming email is converted to a JSON payload with sender, recipients, subject, text/html body, headers, and metadata.
  5. Attachments are stripped — only text content is relayed.
  6. Each inbound email consumes one request from your monthly quota.

Notes:

  • Endpoints are either Webhook endpoint or Email ingestion endpoint — they cannot be both at the same time.
  • Switching an existing endpoint's type clears type-specific settings (e.g. switching to email clears inbound auth, captcha, IP restrictions, CORS, and required headers).
  • The endpoint must be enabled (active) for email ingestion to work.
  • Activity logs show EMAIL_INGESTION_ACCEPTED or EMAIL_INGESTION_REJECTED outcomes for email-sourced relays.

9. Pause and auto-resume

Pause an endpoint temporarily without disabling it permanently. While paused, all inbound relay requests are rejected with 503 Service Unavailable and logged as PAUSED in Activity.

To pause an endpoint:

  1. Open the endpoint in the editor.
  2. Click the Pause button next to the enable/disable control.
  3. Select a duration: 1 hour, 6 hours, 24 hours, or Custom… (1–43200 minutes).
  4. The editor shows a badge: "Paused — resumes in Xh Ym".

To resume early:

  • Click Resume now in the pause badge to clear the pause immediately.
  • The endpoint resumes accepting traffic at once.

Behavior notes:

  • Inbound requests during a pause receive HTTP 503 and are logged with outcome PAUSED.
  • The endpoint auto-resumes after the selected duration — no action needed.
  • Pausing is distinct from disabling: enabled=false endpoints return 404; paused endpoints return 503.
  • The selected resume time is preserved until the endpoint automatically resumes or you resume it manually.

10. URL rotation and lifecycle actions

  • Regenerate URL creates a new endpoint URL immediately.
  • Old URL stops working right away.
  • Endpoint can be enabled/disabled.
  • Delete permanently removes the endpoint and its related activity history.

11. Failure-rate alerts

Configure per-endpoint alerts that fire when the failure rate over a rolling window exceeds a threshold. Optionally auto-pause the endpoint when an alert fires. See the Failure-Rate Alerts guide for details.

Expected result and verification checks

  • Endpoint appears with expected method/format/security settings.
  • Accepted traffic logs as ACCEPTED in Activity.
  • Destination deliveries occur for selected outputs.
  • Google Sheets outputs append rows into the selected spreadsheet and sheet.

Common issues and fixes

  • "No relay targets": create targets first.
  • Email output unavailable: confirm the email target.
  • Google Sheets field selection rejected: add at least one field when save-all is off, and use only payload for XML, text/plain, and None endpoints.
  • Validation failures: check field names/types/patterns.
  • Captcha errors: confirm token field name and provider secret.
  • Delivery failures: check target URL/auth/header/TLS config.
  • Unexpected 3xx failures: PayloadRelay does not follow HTTP redirects. Webhook targets must respond directly with a 2xx status code.

Throughput controls

Each endpoint can set Max requests per minute in the Details tab. Leave it blank to inherit your subscription tier default, or enter a positive integer up to your tier cap. Requests above the effective limit return 429 Too Many Requests with a Retry-After header and are logged as RATE_LIMITED_ENDPOINT.

Related guides

← Back to documentation