# RemoteSiteSetting Metadata Type Reference

> RemoteSiteSetting (.remoteSite-meta.xml) registers an external domain in Salesforce's outbound HTTP callout allowlist for Apex HttpRequest callouts that do not use a NamedCredential.

- Source: https://sfdxtalk.com/docs/metadata/remote-site-setting-metadata-type/
- Category: Metadata
- Applies to: Salesforce Winter '27 (API version 68.0)
- Level: beginner
- Published: 2026-11-12
- Last updated: 2026-11-12
- Publisher: SFDX Talk Editorial (unofficial; not affiliated with or endorsed by Salesforce)
- License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)

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](/docs/metadata/apex-class-metadata-type/) `HttpRequest` or Visualforce callout that specifies a raw `https://...` URL (rather than a `callout:` [NamedCredential](/docs/metadata/named-credential-metadata-type/)) 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.

```mermaid
flowchart TD
    Callout["Apex HttpRequest.setEndpoint(...)"] --> Check{"Uses callout:\nNamedCredential?"}
    Check -->|"Yes"| NC["NamedCredential Authorizes\nDomain & Injects Auth Headers"]
    Check -->|"No (Raw URL)"| RSS{"Active RemoteSiteSetting\nMatches Protocol + Host + Port?"}
    RSS -->|"Yes"| Allow["Outbound Callout Allowed"]
    RSS -->|"No"| Block["Throws System.CalloutException:\nUnauthorized endpoint"]
```

## Key Metadata Fields

| Field | Type | Required | Description |
|---|---|---|---|
| `url` | `string` | Yes | Protocol, domain, and optional port of the external endpoint (for example, `https://api.stripe.com`) |
| `isActive` | `boolean` | Yes | Activates (`true`) or disables (`false`) the allowlist entry |
| `disableProtocolSecurity` | `boolean` | Yes | Always set to `false` in production so HTTPS protocol security is enforced |
| `description` | `string` | No | Documents which integration or Apex class consumes this endpoint |

## Production-Grade XML Example

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

```xml
<?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>
```

> [!TIP]
> **Prefer `NamedCredential` Over `RemoteSiteSetting`**: Whenever possible, use [NamedCredential](/docs/metadata/named-credential-metadata-type/) + [ExternalCredential](/docs/metadata/external-credential-metadata-type/) instead of `RemoteSiteSetting`. Named Credentials eliminate hardcoded endpoint URLs in Apex, manage OAuth 2.0/JWT authentication outside code, and automatically authorize the outbound endpoint without a `RemoteSiteSetting`.

## Auditing Remote Site Settings via Tooling API (`RemoteProxy`)

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

```sql
-- 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.

## Official References

- https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_remotesitesetting.htm