Remote Site Settings
Remote Site Settings is a Salesforce Setup page where administrators register the external URLs that Apex code, Visualforce pages, and certain other platform components are allowed to call.
Definition
Remote Site Settings is a Salesforce Setup page where administrators register the external URLs that Apex code, Visualforce pages, and certain other platform components are allowed to call. Before Apex can make an HTTP callout to any external endpoint, the endpoint's domain must be added to Remote Site Settings as a Remote Site. The platform enforces this allowlist at runtime: a callout to an unregistered domain fails with a security error, preventing unauthorized outbound connections from the org.
The allowlist model is part of Salesforce's defense-in-depth security posture. Without it, any compromised Apex class could call any external URL to exfiltrate data or trigger external actions. With it, every outbound connection requires admin approval through the Setup page, providing a centralized audit point for which external services the org talks to. Remote Site Settings has been part of the platform since the introduction of Apex callouts and remains the standard pattern for outbound HTTP, though modern best practice favors Named Credentials for callouts that need authentication.
How Remote Site Settings enforces outbound security
The allowlist enforcement
When Apex code attempts an HTTP callout (HttpRequest.send), the platform checks the target URL's domain against the Remote Site Settings allowlist. If the domain is registered as a Remote Site, the callout proceeds. If not, the platform throws a System.CalloutException with a clear error message indicating the unauthorized endpoint. The check happens at runtime, not at compile time, so the Apex class compiles successfully but fails when actually executed. This timing means missing Remote Site entries are caught by tests or production execution rather than by deployment, which sometimes catches teams off guard.
URL matching rules
The Remote Site Setting registers a specific URL or URL pattern. The platform matches based on the full URL: scheme (https), host, and port. By default, the registration covers all paths under the registered host. Wildcards are not supported in the host portion, so each subdomain typically requires its own Remote Site entry. The Disable Protocol Security toggle on the Remote Site allows callouts to non-HTTPS endpoints (HTTP, FTP), which is occasionally necessary for legacy systems but generally discouraged because it loses transport encryption. Production-grade integrations should always use HTTPS endpoints.
Remote Site Settings versus Named Credentials
Named Credentials are a more modern alternative to Remote Site Settings for callouts that need authentication. A Named Credential bundles the endpoint URL with authentication configuration (OAuth, JWT, API key, mTLS) into a single addressable artifact. Apex code references the Named Credential by name (callout:MyService/path) and the platform handles authentication automatically. The Named Credential model is preferred for any new integration because it centralizes credential management and avoids hardcoding auth details in Apex. Remote Site Settings remains relevant for callouts that do not need authentication, but most production integrations should migrate to Named Credentials.
The Disable Protocol Security toggle
The Disable Protocol Security checkbox on a Remote Site Setting allows callouts to non-HTTPS URLs. The toggle is off by default, enforcing HTTPS for all outbound traffic. Enabling it for a specific endpoint allows HTTP callouts to that domain, which is necessary for legacy systems that do not support HTTPS or for internal endpoints on trusted networks. Production use of this toggle should be rare and well-documented because every HTTP callout exposes data in transit. Most modern integrations should target HTTPS endpoints regardless of the legacy system's preferences; standing up a TLS-terminating proxy in front of a legacy HTTP service is a common pattern when direct HTTPS is not available.
Multiple environments and URL variation
The Remote Site URL is hardcoded to a specific endpoint. For integrations that have different endpoints in different environments (sandbox calls test-api.acme.com, production calls api.acme.com), the Remote Site entries differ between sandbox and production. The Apex code that issues the callout must adapt to the right URL per environment, typically through Custom Settings or Custom Metadata Types that hold the environment-specific URL. Named Credentials handle this more elegantly because the Apex code references the credential name and the credential itself points at the right URL per environment without code changes.
Auditing and security review
The Remote Site Settings page is one of the standard security review checklists for any Salesforce org audit. Every entry should be reviewed periodically to confirm it is still needed and that the target endpoint is still under the org's control. Stale entries pointing at decommissioned external services represent attack surface; if the external service's domain is reclaimed by a different owner, the org's callouts could be redirected to unexpected destinations. The audit cadence is typically quarterly or annual, with documentation of which entry serves which business purpose. Setup Audit Trail records every change to Remote Site Settings, supporting the audit trail requirement for regulated industries.
Common implementation patterns
Several patterns recur in how teams use Remote Site Settings. Per-integration entries: each external service gets its own Remote Site with a clear name and description. Environment-aware Apex: the callout code reads the target URL from Custom Settings, with different values in sandbox versus production. Migration to Named Credentials: legacy Remote Site-based integrations get progressively migrated to Named Credentials as they need authentication or as part of broader DevOps modernization. Coordination with Connected Apps: the inbound side of an integration uses a Connected App while the outbound side uses Remote Site Settings or Named Credentials. Each pattern has its place; the right choice depends on the integration's specific authentication and lifecycle requirements.
Migrating from Remote Site Settings to Named Credentials
For orgs with substantial Remote Site Settings footprints, migrating to Named Credentials is a worthwhile modernization effort. The process is not automatic but is straightforward: create a new Named Credential for each external service that needs authentication, update the Apex code to reference the Named Credential by name instead of constructing the full URL, retire the corresponding Remote Site entry once no Apex code references the raw URL anymore. The migration produces several benefits. Centralized credential management means credentials live in Named Credentials rather than scattered across Custom Settings, Apex constants, or Protected Custom Metadata. Easier environment promotion means the Apex code does not contain environment-specific URLs; the Named Credential points at the right URL for each environment. Better security posture means credential rotation requires only Named Credential updates, not Apex changes. Audit improvements through the per-Named-Credential Setup Audit Trail. The migration is typically done in phases over multiple quarters because production integrations are mission-critical and each migration requires careful regression testing. Programs that have completed the migration generally report better integration security posture and faster ability to respond to credential rotation incidents. Programs still on Remote Site Settings for authenticated integrations operate with technical debt that grows over time and eventually forces the migration anyway, often during a more stressful security incident than a planned migration would have been.
Configure Remote Site Settings for Apex callouts
Setting up a Remote Site is a straightforward Setup task, but doing it well requires thinking about security, environment differences, and the broader integration architecture. The workflow below covers the standard sequence for adding a new external endpoint that Apex needs to call.
- Identify the endpoint and confirm HTTPS
Document the external endpoint Apex needs to call: the full URL including scheme, host, and port. Confirm the endpoint supports HTTPS. If only HTTP is available, decide whether to enable Disable Protocol Security (rare) or to stand up a TLS-terminating proxy (preferred). Capture the business purpose and the integration owner for the documentation.
- Add the Remote Site in Setup
From Setup, search for Remote Site Settings and click New Remote Site. Provide a descriptive name (no spaces), the full Remote Site URL, a description explaining the business purpose. Leave Disable Protocol Security unchecked unless absolutely necessary. Set the Active checkbox to true. Save. The new Remote Site appears in the list and is immediately effective for Apex callouts.
- Write the Apex callout code
In Apex, construct an HttpRequest with the target URL, set the method (GET, POST, PUT, DELETE), set any required headers, and send through Http.send(). Handle the response: parse the body, check the status code, handle errors gracefully. Cover the code with unit tests using HttpCalloutMock to simulate the external service. Run the tests in sandbox to confirm the callout works as expected.
- Promote across environments and document
Add equivalent Remote Site entries in each environment (UAT sandbox, production) with the appropriate URL for that environment. Promote the Apex code through the standard deployment pipeline. Document the integration in the org's integration runbook: the Remote Site, the Apex class, the external service, the business owner, the error-handling strategy. Schedule a periodic review of the entry to confirm it stays valid as the external service evolves.
Descriptive name (no spaces) identifying the external service the Remote Site allows callouts to.
The full URL including scheme, host, and port that the Remote Site authorizes.
Must be checked for the Remote Site to be effective. Inactive entries do not allow callouts.
Required to create and edit Remote Site Settings in Setup.
The Apex class that issues HttpRequest objects against the registered URL.
- Each subdomain requires its own Remote Site entry. There is no wildcard support for hosts.
- Disable Protocol Security exposes data in transit. Use it only when absolutely necessary and document why.
- Remote Site URL is hardcoded. Environment-specific endpoints require Custom Settings or Custom Metadata Types to hold the URL value.
- Stale entries represent attack surface. Audit quarterly to confirm each entry still serves its purpose.
- Named Credentials are preferred for any callout that needs authentication. Remote Site Settings is best for unauthenticated callouts.
Trust & references
Straight from the source - Salesforce's reference material on Remote Site Settings.
- Remote Site SettingsSalesforce Help
- HttpRequest ClassSalesforce Developer Docs
Hands-on resources to go deeper on Remote Site Settings.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is required before deploying Remote Site Settings-related code to production?
Q2. What is a Governor Limit in the context of Remote Site Settings?
Q3. What skill set is typically needed to work with Remote Site Settings?
Discussion
Loading discussion…