RemoteSiteSetting Metadata Type Reference

The RemoteSiteSetting metadata type registers an external domain and protocol in Salesforce’s Remote Site Settings outbound allowlist. Available in API version 19.0 and later, any outbound ApexClass HttpRequest or Visualforce callout that specifies a raw https://... URL (rather than a callout: NamedCredential) will fail with System.CalloutException: Unauthorized endpoint, please check Setup->Security->Remote site settings unless an active RemoteSiteSetting matches the target protocol, host, and port.

In Salesforce DX projects, remote site settings are stored in force-app/main/default/remoteSiteSettings/ with the .remoteSite-meta.xml suffix.

Key Metadata Fields#

Production-Grade XML Example#

Below is a RemoteSiteSetting (Stripe_Payment_Gateway.remoteSite-meta.xml) authorizing HTTPS callouts to https://api.stripe.com:

<?xml version="1.0" encoding="UTF-8"?>
<RemoteSiteSetting xmlns="http://soap.sforce.com/2006/04/metadata">
    <description>Authorizes outbound HTTPS webhook verification callouts to the Stripe Payment API.</description>
    <disableProtocolSecurity>false</disableProtocolSecurity>
    <isActive>true</isActive>
    <url>https://api.stripe.com</url>
</RemoteSiteSetting>

Auditing Remote Site Settings via Tooling API (RemoteProxy)#

In the Tooling API, RemoteSiteSetting is exposed as the RemoteProxy object:

-- Audit all Remote Site Settings and flag any insecure HTTP or protocol-disabled entries (Tooling API)
SELECT Id, SiteName, EndpointUrl, IsActive, DisableProtocolSecurity, Description
FROM RemoteProxy
ORDER BY SiteName ASC

Frequently asked questions

Do I need a RemoteSiteSetting if my Apex callout uses a NamedCredential?

No. When an Apex HttpRequest or Flow HTTP Callout uses a NamedCredential endpoint (callout:My_Named_Credential), Salesforce automatically authorizes the outbound connection without requiring a RemoteSiteSetting.

When is RemoteSiteSetting still required in modern Salesforce architectures?

RemoteSiteSetting is still required when making Apex callouts to dynamic URLs not bound to a NamedCredential, when calling back into your own org's Tooling or Metadata SOAP/REST APIs via URL.getOrgDomainUrl() without a NamedCredential, or inside managed package post-install scripts.

What does disableProtocolSecurity control on a RemoteSiteSetting?

When disableProtocolSecurity is false (recommended), Salesforce enforces protocol security. Setting it to true allows outbound callouts over unencrypted HTTP from an HTTPS session, which should never be enabled in production.

Does RemoteSiteSetting check the URL path or only the protocol, host, and port?

Salesforce only evaluates the protocol (http/https), domain hostname, and port number of the url field in a RemoteSiteSetting; any trailing path segments in the url field are ignored.

Can I query existing RemoteSiteSettings using the Tooling API?

Yes. Query the RemoteProxy object via the Tooling API to inspect Id, SiteName, EndpointUrl, IsActive, DisableProtocolSecurity, and Description.