Call external APIs
Fetch JSON endpoints with useOrbixFetch, send mutations with useOrbixRequest, and declare allowed outbound domains.
Blocks can make outbound HTTP requests with useOrbixFetch, useOrbixRequest, and orbixFetch. Because community blocks run inside a workspace that may also contain private notes, outbound requests are gated by both your manifest declaration and orbixEgressFirewall.
Declaring network capabilities
Community blocks have network.domains: [] by default — all outbound requests are denied until you list the hostnames your block calls in manifest.capabilities.network:
{
"id": "acme.weather-card",
"name": "Weather Card",
"version": "1.0.0",
"sdk": "^3.0.0",
"capabilities": {
"network": {
"domains": ["api.open-meteo.com"],
"methods": ["GET"]
}
}
}Reactive GET requests (useOrbixFetch)
useOrbixFetch<T>(url, options?) runs a request on mount (unless lazy: true), tracks loading and error strings, and supports caching and polling:
import {
defineBlock,
useOrbixFetch,
type BlockRenderProps,
} from '@orbixdocs/sdk';
interface ForecastResponse {
current_weather?: {
temperature: number;
windspeed: number;
};
}
export default defineBlock({
manifest: {
id: 'acme.weather-card',
name: 'Weather Card',
version: '1.0.0',
sdk: '^3.0.0',
capabilities: {
network: {
domains: ['api.open-meteo.com'],
methods: ['GET'],
},
},
},
component(_props: BlockRenderProps) {
const { data, loading, error, refetch } = useOrbixFetch<ForecastResponse>(
'https://api.open-meteo.com/v1/forecast?latitude=37.77&longitude=-122.42¤t_weather=true',
{
cacheTtl: 60_000,
pollInterval: 0,
}
);
return (
<div
style={{
padding: 16,
borderRadius: 12,
background: 'var(--orbix-card-bg, #16171b)',
border: '1px solid var(--orbix-surface-border, #2a2b32)',
color: 'var(--orbix-text-primary, #f4f4f5)',
}}
>
{loading && <div>Loading forecast...</div>}
{error && <div>Request failed: {error}</div>}
{data?.current_weather && (
<div>
San Francisco: {data.current_weather.temperature}°C (wind{' '}
{data.current_weather.windspeed} km/h)
</div>
)}
<button type="button" onClick={refetch} style={{ marginTop: 8 }}>
Refresh
</button>
</div>
);
},
});Imperative mutations (useOrbixRequest and orbixFetch)
For POST, PUT, PATCH, or DELETE requests triggered by a button click, use useOrbixRequest or orbixFetch.
When calling orbixFetch directly inside an event handler, always read useBlockId() at the component top level and pass { blockId } in the request options. Without blockId, the call is attributed to 'anonymous-block' and fails closed.
import { useBlockId, useOrbixRequest, orbixFetch } from '@orbixdocs/sdk';
export function WebhookButtons() {
const blockId = useBlockId();
// Option A: Hook with built-in loading / error state
const { loading, error, execute } = useOrbixRequest<{ ok: boolean }>(
'https://api.example.com/webhooks/ping',
{ method: 'POST' }
);
// Option B: Low-level Response access
const checkHealth = async () => {
const res = await orbixFetch('https://api.example.com/health', {
method: 'GET',
blockId,
});
return res.status;
};
return (
<div>
<button
type="button"
disabled={loading}
onClick={() => void execute({ event: 'manual_ping' })}
>
Send ping
</button>
<button type="button" onClick={() => void checkHealth()}>
Check status
</button>
{error && <span>{error}</span>}
</div>
);
}Egress firewall rules and limits
How outbound traffic is checked depends on which runtime executes your block:
- React SDK blocks (
orbixEgressFirewall):- Allows only
http:,https:,ws:, andwss:schemes. - Blocks private/loopback IP ranges and cloud metadata addresses (SSRF protection;
localhostis permitted only when Orbix itself is served fromlocalhost). - Blocks Orbix authentication paths (
/api/auth*and/auth/v1*). - Blocks requests carrying registered secret fingerprints or known secret prefixes in unauthorized payloads (DLP check).
- Taint rule: If a community block has read document, workspace, database, or cross-block data,
orbixEgressFirewallmarks that instance as tainted and blocks all subsequent outbound requests from it. - Requires an installed permission grant from
BlockPermissionSheet(orauthorPreview: truewhile editing in Block Studio).
- Allows only
- HTML and polyglot blocks (
OrbixHtmlFrame):- The runner iframe's HTTP Content Security Policy (
connect-src blob: data:) blocks direct browserfetch,XMLHttpRequest,WebSocket, andEventSourceconnections inside the frame. fetch,XMLHttpRequest, andnavigator.sendBeaconare shimmed overpostMessageto the host'shostFetchhandler, which verifiesmanifest.capabilities.network.domainsviacapabilityEngine.verifyNetworkand enforces:10 MBmax request and response size30 srequest timeout8concurrent in-flight requests per block (exceeding throwsSecurityCapabilityErrorwithcapability: 'network:rate')credentials: 'omit'(host cookies are never sent)
- The runner iframe's HTTP Content Security Policy (
WebSockets (useOrbixWebSocket)
useOrbixWebSocket (exported from both @orbixdocs/sdk and @orbixdocs/sdk/realtime) manages WebSocket connections with reconnect backoff in React SDK blocks when capabilities.network.websocket is true and the target host is permitted by orbixEgressFirewall. WebSockets are not available inside cross-origin HTML/polyglot frames because of connect-src blob: data:.
Realtime channels and WebRTC
Sync transient state across tabs with BroadcastChannel, open peer-to-peer WebRTC data channels, or consume SSE and WebSocket feeds.
Use API keys safely
Declare per-block environment variables, read user-supplied keys with useOrbixEnv, and avoid leaking credentials into documents.