Understanding HTTP SSRF protection

Last updated: November 11, 2026

Overview

gaiia protects all outbound HTTP requests against Server-Side Request Forgery (SSRF). This means requests that target internal services, private IP ranges, or localhost are blocked before they leave the platform. In this article, we'll be covering what gets blocked, the error you'll see when a request is blocked, and how to handle it.

Understand what is affected

SSRF protection applies to all outbound HTTP requests made from workflows, including:

  • The HTTP REST Request and HTTP SOAP Request nodes

  • Webhook triggers receiving inbound calls that result in outbound validation

  • Integration HTTP clients (e.g., Preseem, UNMS)

Understand what gets blocked

The following checks are applied to every outbound request before it is sent:

  • Non-HTTP(S) schemes — only http:// and https:// are permitted. Requests using file://, ftp://, or any other scheme are blocked immediately.

  • Localhost — requests to localhost or any subdomain of .localhost are blocked.

  • Private and reserved IP ranges — requests to RFC 1918 private addresses (e.g. 10.x.x.x, 172.16.x.x, 192.168.x.x), loopback (127.x.x.x), link-local (169.254.x.x), carrier-grade NAT, and other reserved ranges are blocked. IPv6 equivalents are also blocked.

  • DNS resolution — when a hostname is used, all DNS records are resolved before the request is sent. If any resolved address falls within a blocked range, the request is rejected. This prevents a hostname from resolving to a public IP during validation but a private IP at connection time. If the hostname cannot be resolved at all, the request is also blocked.

  • Redirects — each redirect target is re-validated before it is followed. Redirects to private IPs, localhost, or disallowed schemes are blocked.

If your environment uses on-premise APIs that resolve to private IP addresses, contact support@gaiia.com to request an allowlist entry for your hostname. Allowlisted hostnames bypass SSRF validation entirely.

Handle a blocked request

When a request is blocked, the node fails with the following error:

  • Error code: HTTP_REQUEST_BLOCKED_URL

  • Error message: Describes which check failed — for example, HTTP request blocked: URL targets a private or reserved IP address.

You can handle this error using the same tools available for any node failure:

  • Add an error link on the HTTP node with the error code HTTP_REQUEST_BLOCKED_URL to route to a recovery path.

  • Add a retry strategy matching HTTP_REQUEST_BLOCKED_URL if the URL is dynamically constructed and may resolve differently on retry.

  • Use the error mapper on the node to reshape the error before downstream logic evaluates it.

For full details on configuring error links and retry strategies, see Handling Node Failures: Retry Strategies, Timeouts, and Error Links.