Skip to content

http-fetch.mdx

Latest commit

 

History

History
151 lines (114 loc) · 4.71 KB

http-fetch.mdx

File metadata and controls

151 lines (114 loc) · 4.71 KB
Raw

HTTP Fetch

Make requests to allow-listed external domains.

Your Devvit app can make network requests to access allow-listed external domains using HTTP Fetch. This enables your app to leverage webhooks, personal servers, and other third-party integrations asynchronously across the network.

Enabling HTTP fetch calls

{
  ...
  "permissions": {
    "http": {
      "enable": true,
      "domains": ["my-site.com", "another-domain.net"]
    }
  }
}

Requesting a domain to be allow-listed

Apps may request a domain to be added to the allow-list by specifying domains in the http configuration. This configuration is optional, and apps can still configure http: true as before.

Requested domains will be submitted for review when you playtest or upload your app. Admins may approve or deny domain requests.

Domain entries must be exact hostnames only, such as nytimes.com or wikipedia.org. These fetch requests are not allowed:

  • Be specific. No using *.example.com when you need api.example.com
  • No wildcards: *.example.com
  • No protocols: https://api.example.com
  • No paths: api.example.com/webhooks

Domains that are approved for your app will be displayed in the Developer Settings section for your app at https://developers.reddit.com/apps/{your-app-slug}/developer-settings. These domains are allow-listed for your app only and not globally.

Apps must request each individual domain that it intends to fetch, even if the domain is already globally allowed. See the global fetch allowlist to view the list of globally allowed domains.

Limitations

  • Access is only allowed to https URIs.
  • Supported HTTP methods: GET, POST, PUT, DELETE, OPTIONS and PATCH.
  • HTTP timeout limit is 30 seconds.

Example usage

Devvit Web applications have two different contexts for using fetch:

Server-side fetch

Server-side fetch allows your app to make HTTP requests to allowlisted external domains from your server-side code (e.g., API routes, server actions):

const response = await fetch('https://example.com/api/data', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
  },
});

const data = await response.json();
console.log('External API response:', data);

Client-side fetch

Client-side fetch has different restrictions and can only make requests to your own webview domain:

Client-side restrictions:

  • Domain limitation: Can only make requests to your own webview domain
  • Endpoint requirement: All requests must target your own /api/... endpoints
  • Authentication: Handled automatically - no need to manage auth tokens
  • No external domains: Cannot make requests to external domains from client-side code
const handleFetchData = async () => {
  // Correct: fetching your own webview's API endpoint
  const response = await fetch("/api/user-data", {
    method: "GET",
    headers: {
      "Content-Type": "application/json",
    },
  });

  const data = await response.json();
  console.log("API response:", data);
};

// Incorrect: cannot fetch external domains from client-side
// const response = await fetch('https://external-api.com/data');

// Incorrect: client-side fetches should target your own /api/... endpoints
// const response = await fetch('/user-data');

Troubleshooting

If you see the following error, it means HTTP Fetch requests are hitting the internal timeout limits. To resolve this:

  • Use a queue or kick off an async request in your back end. You can use Scheduler to monitor the result.
  • Optimize the overall HTTP request latency if you have a self-hosted server.
HTTP request to domain: <domain> timed out with error: context deadline exceeded.

Terms and conditions

Any app that uses fetch must upload Terms and Conditions and a Privacy Policy. Links to each of these documents must be saved in the app details form.

App configuration form

Global fetch allowlist

The following domains are globally allowed and can be fetched by any app:

  • example.com
  • site.api.espn.com
  • cdn.espn.com
  • discord.com
  • api.polygon.io
  • api.massive.com
  • polygon.io
  • slack.com
  • lichess.org
  • api.telegram.org
  • commentanalyzer.googleapis.com
  • language.googleapis.com
  • statsapi.mlb.com
  • api.openai.com
  • api.scryfall.com
  • api.nasa.gov
  • api.sportradar.us
  • api.sportradar.com
  • random.org
  • generativelanguage.googleapis.com
  • youtube.googleapis.com
  • api.weather.gov
  • wikipedia.org
  • finance.yahoo.com
  • api.twitter.com
  • api.petfinder.com
  • fonts.googleapis.com
  • nytimes.com
  • npr.org
  • propublica.org
  • pbs.org
  • i.giphy.com
  • chessboardjs.com