Build a Link Preview Service for User-Submitted URLs
Unfurl user-pasted links safely: fetch Open Graph metadata through an SSRF-safe fetcher, validate og:image and fall back to a 1200×630 screenshot.
When someone pastes a URL into your chat, CMS or bookmarking app, they expect a card with a title, a description and an image. This guide builds the server side of that feature. The pipeline fetches the page, reads its metadata, picks and validates an image, falls back to a screenshot when there isn't one, and caches the result.
This is a different job from two related tasks:
- Publishing preview images for your own pages. There, you control the HTML and design the
og:image. See dynamic OG image generation. - Meeting each platform's image rules. See social media image sizes.
A link preview service consumes other people's URLs. Those URLs are untrusted input that your server will fetch. That makes security the core of the design, not an afterthought.
How unfurling works
Slack's documentation describes the classic approach well. When no app handles a domain, Slack "crawls the URL, looks for common OpenGraph and X (formerly known as Twitter) Card metadata, and renders some micro-approximation of the content" (Slack docs). Your service follows the same pattern, plus a screenshot fallback:
user pastes URL
-> validate URL (scheme, port, host)
-> cache hit? return it
-> fetch HTML through the SSRF-safe fetcher (size and time capped)
-> parse og:* / twitter:* / <title> / description / icon
-> og:image present? fetch it safely, check it, re-encode, store it
-> no usable image? capture a 1200x630 screenshot, store it
-> save the preview JSON with a TTL and return it
Run this in a background job, not in the request that posts the message. Show a skeleton card right away and fill it in when the preview is ready.
Step 1: an SSRF-safe fetcher
Your server will fetch whatever URL a user types. If that URL is http://169.254.169.254/ or resolves to 10.0.0.5, an unprotected fetcher will read your cloud metadata or internal services and show the result in a preview card.
Checking the hostname string isn't enough. Attackers can use:
- DNS names that resolve to private addresses
- DNS rebinding, where a name resolves to a public address on the first lookup and a private one on the next
- IPv6 and IPv4-mapped addresses (
[::ffff:127.0.0.1]) - Numeric hosts (
http://2130706433/,http://0x7f000001/) - Redirects from a public URL to a private one
The fetcher below checks the address at connect time. It does that through the lookup option of Node's http module, so the address that's validated is the address that gets used. It also re-validates every redirect hop and caps size and time. It uses only Node.js built-ins.
// safe-fetch.mjs
import dns from 'node:dns';
import http from 'node:http';
import https from 'node:https';
import net from 'node:net';
const blockList = new net.BlockList();
const IPV4_BLOCKED = [
['0.0.0.0', 8], ['10.0.0.0', 8], ['100.64.0.0', 10], ['127.0.0.0', 8],
['169.254.0.0', 16], ['172.16.0.0', 12], ['192.0.0.0', 24], ['192.0.2.0', 24],
['192.168.0.0', 16], ['198.18.0.0', 15], ['198.51.100.0', 24], ['203.0.113.0', 24],
['224.0.0.0', 4], ['240.0.0.0', 4],
];
const IPV6_BLOCKED = [
['::', 128], ['::1', 128], ['64:ff9b::', 96], ['100::', 64],
['2001:db8::', 32], ['fc00::', 7], ['fe80::', 10], ['ff00::', 8],
];
for (const [range, prefix] of IPV4_BLOCKED) blockList.addSubnet(range, prefix, 'ipv4');
for (const [range, prefix] of IPV6_BLOCKED) blockList.addSubnet(range, prefix, 'ipv6');
export function isBlockedAddress(address) {
const family = net.isIP(address);
if (family === 0) return true;
if (family === 6) {
const mapped = address.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i);
if (mapped) return blockList.check(mapped[1], 'ipv4');
}
return blockList.check(address, family === 6 ? 'ipv6' : 'ipv4');
}
export function assertPublicUrl(rawUrl) {
const url = new URL(rawUrl); // normalizes numeric hosts such as 0x7f000001
if (url.protocol !== 'http:' && url.protocol !== 'https:') throw new Error('Only http and https URLs are allowed');
if (url.username || url.password) throw new Error('Credentials in URLs are not allowed');
if (url.port && url.port !== '80' && url.port !== '443') throw new Error('Non-standard ports are not allowed');
const host = url.hostname.replace(/^\[|\]$/g, '');
if (host === 'localhost' || host.endsWith('.localhost')) throw new Error('Blocked host');
if (net.isIP(host) && isBlockedAddress(host)) throw new Error(`Blocked address ${host}`);
return url;
}
export function safeLookup(hostname, options, callback) {
dns.lookup(hostname, { ...options, all: true }, (error, addresses) => {
if (error) return callback(error);
if (addresses.length === 0 || addresses.some((entry) => isBlockedAddress(entry.address))) {
return callback(new Error(`Blocked address for ${hostname}`));
}
if (options.all) return callback(null, addresses);
return callback(null, addresses[0].address, addresses[0].family);
});
}
export function safeGet(rawUrl, opts = {}) {
const { maxBytes = 512 * 1024, timeoutMs = 5000, maxRedirects = 3, accept = 'text/html', truncate = false } = opts;
return new Promise((resolve, reject) => {
let url;
try {
url = assertPublicUrl(rawUrl);
} catch (error) {
return reject(error);
}
const client = url.protocol === 'https:' ? https : http;
const req = client.get(url, {
lookup: safeLookup,
signal: AbortSignal.timeout(timeoutMs),
headers: { accept, 'user-agent': 'ExampleLinkPreview/1.0 (+https://example.com/bot)' },
}, (res) => {
const status = res.statusCode ?? 0;
if (status >= 300 && status < 400 && res.headers.location) {
res.resume();
if (maxRedirects === 0) return reject(new Error('Too many redirects'));
const next = new URL(res.headers.location, url).href;
return resolve(safeGet(next, { ...opts, maxRedirects: maxRedirects - 1 }));
}
const chunks = [];
let size = 0;
let finished = false;
const finish = () => {
if (finished) return;
finished = true;
resolve({ url: url.href, status, headers: res.headers, body: Buffer.concat(chunks) });
};
res.on('data', (chunk) => {
size += chunk.length;
if (size > maxBytes) {
if (truncate) {
chunks.push(chunk.subarray(0, chunk.length - (size - maxBytes)));
finish();
res.destroy();
} else {
req.destroy(new Error('Response too large'));
}
return;
}
chunks.push(chunk);
});
res.on('end', finish);
res.on('error', reject);
});
req.on('error', reject);
});
}
Adapt the block list to your network. Add your VPC ranges if they're unusual, and block any internal hostnames your cloud provider exposes. Libraries such as request-filtering-agent and ssrf-req-filter take a similar approach. If you'd rather use one, check how it handles redirects, IPv6 and connect-time checks before you rely on it.
As a second line of defense, run the preview worker where it can't reach internal services at all, for example in a separate network segment with outbound-only access.
Step 2: parse the metadata
Parse the HTML with cheerio (npm install cheerio). Read Open Graph tags first, then X card tags, then plain HTML. The Open Graph protocol defines og:image:url as identical to og:image, and og:image:alt as a description of the image.
// metadata.mjs
import * as cheerio from 'cheerio';
const clamp = (value, max) => (value ? value.replace(/\s+/g, ' ').trim().slice(0, max) || undefined : undefined);
export function extractMetadata(html, pageUrl) {
const $ = cheerio.load(html);
const meta = (selector) => $(selector).first().attr('content') || undefined;
const absolute = (value) => {
if (!value) return undefined;
try {
const resolved = new URL(value, pageUrl);
return resolved.protocol === 'http:' || resolved.protocol === 'https:' ? resolved.href : undefined;
} catch {
return undefined;
}
};
return {
title: clamp(meta('meta[property="og:title"]') ?? meta('meta[name="twitter:title"]') ?? $('title').first().text(), 200),
description: clamp(meta('meta[property="og:description"]') ?? meta('meta[name="twitter:description"]') ?? meta('meta[name="description"]'), 300),
siteName: clamp(meta('meta[property="og:site_name"]'), 100),
image: absolute(meta('meta[property="og:image"]') ?? meta('meta[property="og:image:url"]') ?? meta('meta[name="twitter:image"]')),
imageAlt: clamp(meta('meta[property="og:image:alt"]'), 300),
favicon: absolute($('link[rel~="icon"]').first().attr('href')) ?? new URL('/favicon.ico', pageUrl).href,
};
}
Relative og:image values are resolved against the final URL after redirects, and only http and https results are kept. Text fields are trimmed and length-capped, so a page can't push a 50 KB "title" into your UI.
This reads only the server-rendered HTML. Most sites put their sharing tags there because social crawlers don't run JavaScript either. A few single-page apps add tags only on the client; those pages will usually get the screenshot fallback.
Step 3: validate and store the og:image
Don't trust og:image. It can be a 404, a tracking pixel, an SVG, a 40 MB photo or an internal address. Fetch it through the same safe fetcher with a larger size cap. Check the type and dimensions, then re-encode it into your own storage:
// preview-image.mjs
import sharp from 'sharp';
import { safeGet } from './safe-fetch.mjs';
export async function importOgImage(imageUrl, store) {
try {
const res = await safeGet(imageUrl, { maxBytes: 5 * 1024 * 1024, accept: 'image/*', timeoutMs: 8000 });
const type = String(res.headers['content-type'] ?? '');
if (res.status !== 200 || !type.startsWith('image/') || type.includes('svg')) return null;
const image = sharp(res.body, { limitInputPixels: 40_000_000 });
const { width = 0, height = 0 } = await image.metadata();
if (width < 200 || height < 200) return null;
const webp = await image
.resize(1200, 630, { fit: 'cover', position: 'centre', withoutEnlargement: true })
.webp({ quality: 80 })
.toBuffer();
return store(webp, 'image/webp');
} catch {
return null;
}
}
The 200×200 floor follows Meta's documented minimum for shared images. Pick your own threshold for what your card can show.
Re-encoding through sharp does three things. It turns an arbitrary upstream file into a known format. It drops anything that isn't a decodable raster image. And it means your users' browsers load images from your domain, so third-party servers don't see who is viewing a conversation.
store(buffer, contentType) is your function. It writes to your bucket or CDN origin and returns a public URL.
Step 4: screenshot fallback
When there's no usable og:image, capture the page. A 1200×630 viewport gives a 1.91:1 image, the same shape most cards use:
{
"url": "https://example.com/article",
"width": 1200,
"height": 630,
"format": "webp",
"quality": 80,
"blockAds": true
}
// screenshot-fallback.mjs
export async function captureFallback(pageUrl, store) {
const res = await fetch('https://screenshotly.app/api/screenshot', {
method: 'POST',
headers: {
'x-api-key': process.env.SCREENSHOTLY_API_KEY,
'content-type': 'application/json',
},
body: JSON.stringify({ url: pageUrl, width: 1200, height: 630, format: 'webp', quality: 80, blockAds: true }),
});
if (!res.ok) {
console.warn(`Screenshot fallback failed (${res.status}): ${await res.text()}`);
return null;
}
return store(Buffer.from(await res.arrayBuffer()), 'image/webp');
}
Some points to note:
- Store the bytes. Never link to the API. The capture endpoint needs your API key and returns the image as an attachment, so it can't be used as an
<img src>. - Expect a cost of one capture per uncached URL. Failed captures don't count against your quota. Caching (Step 5) keeps repeat pastes free.
blockAdsworks on every plan and hides common ad and consent containers. On Growth and above you can addaiRemovalwith types such ascookie-bannerandchat-widgetfor cleaner fallbacks.- Screenshotly runs its own checks. It rejects private and internal target URLs with a
400. That protects Screenshotly's browser, not your metadata fetcher, which is why Step 1 exists.
For timing options on slow or script-heavy pages, see capturing dynamic content.
Step 5: put it together with caching
// preview-service.mjs
import crypto from 'node:crypto';
import { assertPublicUrl, safeGet } from './safe-fetch.mjs';
import { extractMetadata } from './metadata.mjs';
import { importOgImage } from './preview-image.mjs';
import { captureFallback } from './screenshot-fallback.mjs';
const OK_TTL = 24 * 60 * 60;
const FAILED_TTL = 15 * 60;
export async function getPreview(rawUrl, { cache, store, refresh = false }) {
const url = assertPublicUrl(rawUrl);
url.hash = '';
const key = `preview:${crypto.createHash('sha256').update(url.href).digest('hex')}`;
if (!refresh) {
const cached = await cache.get(key);
if (cached) return JSON.parse(cached);
}
let preview;
try {
const page = await safeGet(url.href, { truncate: true });
const type = String(page.headers['content-type'] ?? '');
if (page.status >= 400 || !type.includes('html')) throw new Error(`Unusable page (${page.status})`);
const meta = extractMetadata(page.body.toString('utf8'), page.url);
const ogImage = meta.image ? await importOgImage(meta.image, store) : null;
const image = ogImage ?? (await captureFallback(page.url, store));
preview = {
...meta,
url: page.url,
image,
imageAlt: ogImage ? meta.imageAlt : undefined,
imageSource: ogImage ? 'og' : image ? 'screenshot' : 'none',
ok: true,
};
} catch {
preview = { url: url.href, title: url.hostname, ok: false };
}
await cache.set(key, JSON.stringify(preview), preview.ok ? OK_TTL : FAILED_TTL);
return preview;
}
cache is any store with get(key) and set(key, value, ttlSeconds), such as Redis. A few choices are worth spelling out:
- Failures are cached briefly. A dead or blocked URL gets a short TTL, so a busy channel doesn't trigger a fetch on every render.
refresh: trueskips the cache. Expose it as a "refresh preview" action for users, rate-limited. A site that changed its image doesn't have to wait for the TTL.- The key is the normalized URL. Query strings are kept, because they often select different content.
imageSourcerecords where the image came from, so you can measure how often you need the paid fallback.
For layered caching patterns, see screenshot caching strategies.
Step 6: render safely
Everything in the preview came from an untrusted page. Render it as text, never as HTML, and allow only http and https links:
function LinkPreviewCard({ preview }) {
const href = /^https?:\/\//i.test(preview.url) ? preview.url : undefined;
if (!href) return null;
return (
<a href={href} className="link-preview" target="_blank" rel="noopener noreferrer nofollow ugc">
{preview.image && (
<img src={preview.image} alt={preview.imageAlt ?? ''} width={600} height={315} loading="lazy" />
)}
<div className="link-preview-body">
<span className="link-preview-site">{preview.siteName ?? new URL(href).hostname}</span>
<strong className="link-preview-title">{preview.title}</strong>
{preview.description && <p className="link-preview-description">{preview.description}</p>}
</div>
</a>
);
}
React escapes text content by default. Don't bypass it with dangerouslySetInnerHTML. preview.image always points at your storage, so you can lock down img-src in your Content Security Policy to your own CDN.
Abuse limits
A preview endpoint makes your server fetch URLs on a user's behalf. Without limits, it can be used to probe or flood other sites:
- Per user: cap preview requests per minute and per day.
- Per target host: cap concurrent fetches to the same hostname, so one message with 50 links to one site doesn't hit it 50 times at once.
- Per workspace: cap screenshot fallbacks, since each one uses a capture from your plan.
- Identify your fetcher with a descriptive user agent and a contact URL, as in the example above, and honor opt-out requests.
On the Screenshotly side, a 429 response includes Retry-After. Respect it in your job runner. The error handling guide covers retry logic, and the security guide covers key handling.
Checklist
- Treat every pasted URL as untrusted. Validate at connect time, on every redirect, with size and time caps.
- Prefer the page's own
og:image. Validate it, re-encode it and store it yourself. - Fall back to a 1200×630 screenshot, stored in your bucket and never linked from the API.
- Cache successes and failures with different TTLs, and offer a rate-limited manual refresh.
- Render metadata as text, links as
http(s)only, and images from your own domain.
You can try capture settings in the playground, or create a free account for an API key. The Free plan includes 100 captures. For a lower-level walkthrough of calling the API from Node.js, see the Node.js tutorial.
About the Author

Asad Ali
CTO at ZTABS and the developer behind Screenshotly. Writes about screenshot automation, API design, and building reliable SaaS backends with Next.js, Node.js, and TypeScript.
Credentials: CTO at ZTABS, full-stack developer, builder and maintainer of Screenshotly and its official JavaScript and Python clients
Frequently Asked Questions
Should I use the page's og:image or a screenshot?
Use the page's own og:image first. It is the image the site owner chose for sharing, and it's what platforms like Slack fall back to when they unfurl a link. Use a screenshot only when og:image is missing, broken or too small. Either way, copy the final image into your own storage instead of hotlinking it.
Does the screenshot API protect my metadata fetcher from SSRF?
No. Screenshotly rejects private and internal target URLs for its own captures, but your server fetches the HTML and og:image itself. That fetcher needs its own protection: resolve DNS and block private ranges at connect time, re-check every redirect, allow only http and https on standard ports, and cap response size and time.
Can I put the screenshot API URL straight into an img tag?
No. The capture endpoint needs your API key and returns the image as a download, so it isn't a usable public image URL. Capture on your server, store the bytes in your bucket or CDN, and serve that URL.
How long should I cache a preview?
Pick a TTL that suits your product, for example one day for chat and longer for bookmarks, and give users a manual refresh. Cache failures too, with a short TTL, so a broken URL isn't fetched again on every render.
Does stealth mode get previews for sites that block bots?
Not reliably. Screenshotly's stealth option (Basic and up) sends a desktop browser user agent and hides some automation signals, but it isn't a guaranteed way past bot protection. Respect the site's terms and show a minimal preview when a site refuses.
Ready to capture your first screenshot?
Get started with 100 free screenshots. No credit card required.