ScreenshotAPI.net Webhook and Callback Options Explained

Short answer: ScreenshotAPI.net’s public documentation describes sending a screenshot request and receiving an HTTP response. It documents IMAGE output for screenshot bytes and JSON output for a hosted screenshot URL and metadata. The reviewed materials do not establish whether ScreenshotAPI.net can send a separate outbound webhook or call a URL you provide, so confirm that capability with its support team before building around it.

This distinction matters: a browser wait event controls when the remote page is captured; a webhook or callback URL, in the usual application-integration sense, is a later HTTP request sent from the service to your server. Documentation of a render wait event does not establish outbound webhook support.

What “webhook” and “callback” can mean

People use “callback” for two different things in screenshot workflows:

Capture timing: wait until the target page reaches a browser lifecycle event such as load or networkidle, then take the screenshot.
Completion notification: after processing a request, the screenshot service sends a new HTTP request to a callback URL you supplied.

ScreenshotAPI.net’s documented wait_for_event option belongs to the first meaning. It controls when rendering proceeds in the target browser. The reviewed public materials describe request/response integration and response modes, but do not verify the second meaning: an outbound notification to your application.

Accordingly, do not treat JSON output, a hosted screenshot URL, or a browser wait event as proof of asynchronous execution or a webhook. The public documentation reviewed does not settle whether webhook support exists in an account-specific or undocumented form.

How the documented request and response work

The official v3 render endpoint is https://shot.screenshotapi.net/v3/screenshot. Its render documentation shows a GET request with a token and target URL; the getting-started guide also documents GET and POST integration. Use the current endpoint documentation for the exact parameters your account needs.

Output mode	What the caller receives	Useful when
IMAGE	Raw screenshot bytes in the HTTP response body	Your application needs to save or process the image file directly.
JSON	A hosted screenshot URL and metadata	Your workflow needs a result reference and associated status information.

JSON is a response format, not evidence of a later server-to-server callback. In both cases, build your integration to handle the HTTP response to the request you initiated.

Runnable request examples

These examples show the documented request/response pattern. Check the current ScreenshotAPI.net render documentation for required parameter names and the appropriate output-mode option for your account. Keep the token on the server side and avoid putting it into public client code.

cURL

curl -G 'https://shot.screenshotapi.net/v3/screenshot' \
  --data-urlencode 'token=YOUR_SCREENSHOTAPI_TOKEN' \
  --data-urlencode 'url=https://example.com' \
  -o screenshot-response

The output is saved as a response body. Select the documented IMAGE response mode when you need image bytes; for JSON mode, inspect the response as JSON and use its hosted URL and metadata.

Python

import os
import requests

endpoint = "https://shot.screenshotapi.net/v3/screenshot"
params = {
    "token": os.environ["SCREENSHOTAPI_TOKEN"],
    "url": "https://example.com",
}

response = requests.get(endpoint, params=params, timeout=90)
response.raise_for_status()

content_type = response.headers.get("content-type", "")
if "application/json" in content_type:
    result = response.json()
    print("Screenshot result:", result)
else:
    with open("screenshot-response", "wb") as image_file:
        image_file.write(response.content)
    print("Saved image response")

Install the dependency with python -m pip install requests. Set SCREENSHOTAPI_TOKEN in the process environment before running the script.

Node.js

const endpoint = new URL('https://shot.screenshotapi.net/v3/screenshot');
endpoint.searchParams.set('token', process.env.SCREENSHOTAPI_TOKEN);
endpoint.searchParams.set('url', 'https://example.com');

const response = await fetch(endpoint, { signal: AbortSignal.timeout(90_000) });
if (!response.ok) {
  throw new Error(`Screenshot request failed: HTTP ${response.status}`);
}

const contentType = response.headers.get('content-type') || '';
if (contentType.includes('application/json')) {
  const result = await response.json();
  console.log('Screenshot result:', result);
} else {
  const bytes = new Uint8Array(await response.arrayBuffer());
  await (await import('node:fs/promises')).writeFile('screenshot-response', bytes);
  console.log('Saved image response');
}

Run with SCREENSHOTAPI_TOKEN set in the environment. This uses Node’s built-in fetch in current Node versions.

POST requests

The getting-started material documents both GET and POST. POST can be useful when your integration prefers request parameters in a body or needs to avoid placing a long target URL in the query string. Follow the vendor’s current POST example for its accepted content type and parameter encoding; do not assume a body format without checking the API documentation.

How to design a workflow that needs completion notification

Decide which result your application needs. Use IMAGE when your process consumes bytes; use JSON when it needs the hosted result URL and metadata.
Make the screenshot request from a backend worker. Store the token in a secret manager or server environment, not in browser JavaScript or a mobile app.
Handle the initiating HTTP response. Check for HTTP errors, parse the body according to its content type, and persist either the bytes or the returned result reference.
Make your own application notification. If a user, job system, or downstream service needs notification, your backend can send it after it has received and stored the response.
Confirm provider-side webhook details before relying on them. Ask ScreenshotAPI.net whether callbacks are currently supported, and request the exact parameter names, delivery guarantees, retry behavior, signing method, and payload schema.

If the vendor confirms an asynchronous webhook option, validate signatures if offered, make the receiver idempotent, record event IDs or other deduplication keys when available, and tolerate retries and delayed delivery. Those are general webhook integration practices; the reviewed ScreenshotAPI.net materials do not establish that it offers those mechanisms.

Capture timing is separate from callback delivery

A wait setting decides when the browser should capture the target. A page may fire load before client-side content appears, while waiting for network idle can take longer or never settle on pages with persistent connections. JavaScript injection runs in the target browser context before capture. Neither mechanism sends a notification to your application.

Choose a capture condition based on what must appear in the image, and use an explicit selector or bounded delay if the page’s content requires it and the API supports that option. Set a caller-side timeout appropriate for the render duration, and handle timeout failures as failed requests rather than assuming a callback will arrive.

Cache, quota, and operational considerations

ScreenshotAPI.net’s help material says cached requests do not count toward quota unless the caller opts to request only fresh screenshots. It also describes retention of up to 30 days for the free tier and six months for paid tiers. These details can change, so verify the current plan terms before making storage, quota, or compliance decisions.

Caching may let an integration reuse a recent result, but it does not answer whether a callback exists. Decide whether freshness or reuse matters for your use case, and make the choice explicit in the request according to the current API options.

Performance: render time depends on the target page and capture conditions. Waiting for extra events or long delays adds latency. The vendor’s features page makes performance claims, but they are undated vendor claims and are not used here as independent guarantees.
Reliability: treat each API request as a network operation that can fail or time out. Use bounded retries for transient failures, avoid retrying permanent configuration errors, and make result storage idempotent.
Cost: include cache behavior, fresh-render requirements, output storage, and retry volume in quota planning. Check current plan limits and retention terms rather than relying on older figures.
Credentials: the help page says keys can be rolled in the dashboard, revoking the prior key. It also says domain restriction for API keys was unavailable when that answer was written. Check current key controls and rotate a key if it is exposed.

Troubleshooting

Symptom	Likely cause	What to do
No request arrives at your callback endpoint	Callback support or configuration has not been established; a capture wait event is not a webhook.	Confirm support and exact setup with ScreenshotAPI.net. Until confirmed, consume the initiating HTTP response in your backend.
The response is image data when JSON was expected, or the reverse	The selected response mode differs from what the caller assumes.	Set the documented output mode explicitly and branch on the response content type.
The saved file cannot be opened as an image	The response may be JSON, an HTTP error body, or another non-image response saved under an image filename.	Check the HTTP status and content type before writing bytes as an image; inspect JSON responses separately.
A request fails authentication	The token is missing, invalid, or has been rolled and revoked.	Check the server-side secret and dashboard key state. Update the secret after rolling a key.
The render times out or misses dynamic content	The page is slow, the selected wait condition fires too early, or network activity never settles.	Review capture timing options, allow an appropriate bounded timeout, and use a page-specific readiness condition when available.
Quota usage differs from expected	Cache hits and fresh-render settings affect whether requests count, and plan details may have changed.	Inspect current help and plan terms, and verify whether the request used cached output or forced a fresh render.

Or skip the browser setup

ScreenshotNeo provides a screenshot API and MCP server for developers. A single GET request returns a screenshot or PDF; the documented call below requests a WebP image. See the ScreenshotNeo API documentation for request options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

ScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.

FAQ

Does ScreenshotAPI.net support webhooks?

The reviewed public documentation does not establish that it does. Ask the vendor to confirm current support before designing around a webhook.

Can ScreenshotAPI call a callback URL when a screenshot is ready?

The reviewed materials do not verify a caller-supplied callback URL feature. A wait event controls browser capture timing and is a different mechanism.

How do I get notified when ScreenshotAPI finishes a screenshot?

For the documented request/response flow, handle the response in the service that initiated the request, then notify your own users or downstream systems from your backend. Confirm with ScreenshotAPI support if you need a provider-sent notification.

Does ScreenshotAPI return a URL or the image itself?

The documented modes include IMAGE, which returns image bytes, and JSON, which returns a hosted screenshot URL and metadata.